Luis Martinez - Web Developer

How to Use Two GitHub Accounts on One Machine Without Switching Anything

2026-08-23T00:00:00+00:00

Tl,dr:

One default GitHub account. A second account that takes over for every repo under one folder.
No switching. No git config user.email per clone. No "oops, pushed to work as my personal self".
Three separate things have to agree: your git identity, your SSH key, and the gh CLI. They live in three different places and none of them know about each other.
Two traps will silently break this and give you no error message. Both are at the bottom, with proof.
Two more things that break it later: logging in a new account hijacks your global default, and moving a scoped folder reverts that tree to your default identity without complaining.
There is a copy-paste prompt at the end of each part, if you want an agent to just do it.

Why is this so annoying?

You have a personal GitHub account. Then you get a client, or a job, and now you have a work GitHub account too.

So you clone the work repo and push.

And the commit shows up under your personal name and email.

Or worse, it doesn't show up at all, because your personal SSH key has no access to the work org, and git yells at you about a repository that "does not exist".

The usual fix you land on is git config user.email work@example.com in every work clone.

That works until you forget once.

I wanted a rule instead:

Everything under ~/dev/work is the work account. Everything else is me.

No thinking. No switching. Just a folder.

Here's how to build that from nothing.

Why is this three problems and not one?

This is the part that trips people up, so it's worth 30 seconds of your time.

When you push to GitHub, three completely independent systems get involved.

Identity. The name and email baked into the commit object. This is just text. Git does not verify it. Lives in ~/.gitconfig.
Transport. The SSH key that proves to GitHub who you are. This is what actually decides whether your push is allowed. Lives in ~/.ssh/config.
The API. The gh CLI, for gh pr create, gh repo view and friends. Its own token, its own keyring. Knows nothing about your git config or your SSH setup.

You can get all three wrong independently.

Think about how bad that is. Your commit can be authored as your work self, while being pushed with your personal key, while gh pr create fails because it's talking to GitHub as a third identity.

So we configure all three. And we make all three key off the same folder.

There's a fourth thing, commit signing, which is really a sub-problem of identity. I'll cover it. Get it wrong and GitHub stamps "Unverified" on every commit you make, and you will not know why.

Part 1: How do you set it up from scratch?

Assume your machine is completely fresh. Nothing configured.

I'll use these placeholders. Swap in your own:

personal-user and work-user: the two GitHub usernames
personal@example.com and work@example.com: the two emails
~/dev/work: the folder that belongs to the work account

1. Make two SSH keys

One key per account. GitHub will NOT let two accounts share a key.

ssh-keygen -t ed25519 -C "personal@example.com" -f ~/.ssh/id_ed25519
ssh-keygen -t ed25519 -C "work@example.com"     -f ~/.ssh/id_ed25519_work

Add each of your public keys to its own GitHub account, under Settings → SSH and GPG keys → New SSH key, key type Authentication.

cat ~/.ssh/id_ed25519.pub       # paste into personal-user
cat ~/.ssh/id_ed25519_work.pub  # paste into work-user

2. Write `~/.ssh/config`

This is your default. It pins your personal key for github.com.

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

That last line is not optional, and it's the one you'll leave out.

Why does it matter? Without it, SSH offers every key in your agent, in agent order, and GitHub accepts the first valid one. Both of your keys are valid.

So the account you land on depends on which key you happened to load first.

It will work for weeks and then break on a Tuesday.

3. Write a second SSH config, for work only

Create ~/.ssh/config-work:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Yes, it declares Host github.com again.

That's the whole point. This file is going to replace ~/.ssh/config for work repos, not get merged into it.

Lock both down:

chmod 600 ~/.ssh/config ~/.ssh/config-work

4. Write `~/.gitconfig`

Your default identity, plus one conditional include at the bottom.

[user]
	name = Your Name
	email = personal@example.com

[init]
	defaultBranch = main

# Always reach GitHub over SSH, never HTTPS, so the KEY decides the account
# instead of a cached token.
[url "git@github.com:"]
	insteadOf = https://github.com/

# Work account override. This is LAST on purpose: git applies config in file
# order, so whatever is in here wins inside that folder.
[includeIf "gitdir:/home/you/dev/work/"]
	path = /home/you/dev/work/.gitconfig-work

Three things you should know about that includeIf:

Use an absolute path. ~ works in newer git versions. Absolute paths always work.
Keep the trailing slash. gitdir:/home/you/dev/work/ matches that folder and everything below it. Drop the slash and you're matching a filename pattern instead, and it gets weird.
It matches where the REPO is, not where you are. So git -C ~/dev/work/thing status from anywhere still gets you the work identity. That's good, and it's why the folder rule is reliable.

It also doesn't leak into look-alike folders. ~/dev/work-notes and ~/dev/workX stay personal.

I tested that one. It's exact.

5. Write `~/dev/work/.gitconfig-work`

The override. Identity, SSH key, and signing.

[user]
	name = Your Name
	email = work@example.com

# Pin the work SSH key for every git network operation in this tree.
# -F REPLACES ~/.ssh/config, so the personal key is not even a candidate.
[core]
	sshCommand = ssh -F /home/you/.ssh/config-work

# Sign with the work SSH key, not your personal GPG key.
[gpg]
	format = ssh
[user]
	signingkey = /home/you/.ssh/id_ed25519_work.pub
[commit]
	gpgsign = true
[tag]
	gpgsign = true

That core.sshCommand line is doing the heavy lifting here.

It's the only mechanism I found that is genuinely airtight. The obvious alternatives are not, and I put both of them in the traps section at the bottom, with the output that proves it.

6. Make commit signing actually verify

If you turn on signing, do it properly or turn it off.

Half-configured signing is worse than none. GitHub renders "Unverified" on every commit, and most people never work out why.

Here's the rule GitHub uses: the signing key must be registered on the account, AND it must be associated with the email in the commit.

So go to the work account's Settings → SSH and GPG keys → New SSH key and add the work public key a SECOND time, this time with key type Signing Key.

cat ~/.ssh/id_ed25519_work.pub

Same key, added twice. Once as Authentication, once as Signing. GitHub treats those as two different things.

This is the step you are most likely to miss in the whole setup.

You can check what's registered without even logging in, because it's public:

curl -s https://api.github.com/users/work-user/ssh_signing_keys

Empty array? Then GitHub will mark your commits Unverified, no matter how correct your local config is.

While you're here, teach git to verify SSH signatures locally too. Otherwise git log --show-signature just shrugs at you. Create ~/.config/git/allowed_signers:

work@example.com ssh-ed25519 AAAAC3Nz...paste the key part here

And point git at it in ~/.gitconfig:

[gpg "ssh"]
	allowedSignersFile = /home/you/.config/git/allowed_signers

7. Make the gh CLI follow the folder too

Log into both of your accounts. gh supports this natively and keeps both tokens around:

gh auth login   # do this twice, once per account
gh auth status  # should list both

One thing that will catch you on that second login: gh auth login has no --user flag. You cannot tell it which account to log in as.

$ gh auth login -u work-user
unknown shorthand flag: 'u' in -u

The account is decided by whoever you happen to be signed in as in the browser when you complete the flow. So before the second login, sign out of GitHub in your browser or run the flow in a private window. Otherwise you will authenticate as the same account twice and wonder why gh auth status only ever lists one.

-u does exist on gh auth token and gh auth switch. Just not on login. That inconsistency is the whole trap.

One more thing, and it bites harder than it looks: gh auth login makes whichever account you just logged in as the globally active one.

The wrapper below injects a token per invocation for your scoped folders, so those stay correct. But everywhere else it deliberately does nothing and lets gh use the active account. Which you just changed.

So the moment that second login finishes, every personal repo on the machine is quietly talking to GitHub as your work self:

$ cd ~/code/personal-thing && gh api user --jq .login
work-user          # wrong, and nothing told you

Switch back once, right after logging in:

gh auth switch -u personal-user
gh auth status              # confirm: personal is Active, the rest are not

This is the same failure mode as everything else in this post. Nothing errors. The wrong identity just becomes the default and waits.

But gh has no idea what folder you're in. It uses whichever account is globally "active".

So in a work repo you get this:

$ gh repo view
GraphQL: Could not resolve to a Repository with the name 'work-user/thing'

It's asking as your personal self, which cannot see the repo.

Now you will say: just use gh auth switch, Luis!

Sure. But that's global mutable state you have to remember to flip back, which is exactly the thing we're trying to get rid of.

Better: a tiny wrapper on your PATH that picks the account per invocation. Put this at ~/.local/bin/gh, and make sure ~/.local/bin comes before /usr/bin in your PATH:

#!/bin/bash
# Pick the GitHub account per invocation, mirroring the git folder rule.

GH_BIN=/usr/bin/gh
WORK_TREE="$HOME/dev/work"
WORK_ACCOUNT=work-user
# Owners belonging to the work account, for when a repo is named explicitly.
WORK_OWNERS='work-user|SomeWorkOrg'

use_work=0
[[ "$(pwd -P)/" == "$WORK_TREE/"* ]] && use_work=1
[[ $* =~ (^|[[:space:]=/])($WORK_OWNERS)/ ]] && use_work=1
[[ $GH_REPO =~ ^($WORK_OWNERS)/ ]] && use_work=1

# Exclude `gh auth ...` so login/logout/status keep working on the real
# account list instead of on an injected token.
if [[ $use_work -eq 1 && "$1" != "auth" ]]; then
    token=$("$GH_BIN" auth token -u "$WORK_ACCOUNT" 2>/dev/null)
    if [[ -n "$token" ]]; then
        GH_TOKEN="$token" exec "$GH_BIN" "$@"
    fi
    echo "gh: no stored token for $WORK_ACCOUNT" >&2
fi

exec "$GH_BIN" "$@"

chmod +x ~/.local/bin/gh

GH_TOKEN is scoped to that one process. Your globally active account is never touched, so there's no state to forget to reset.

The WORK_OWNERS check is there for a case the folder rule genuinely can't cover: gh pr list -R SomeWorkOrg/thing, run from your home directory. There's no repo folder to look at, so we match on the owner name instead.

And notice it's a shell script on PATH, not an alias or a shell function. That matters more than it looks. It keeps working inside scripts, inside Makefiles, in non-interactive shells, and when your editor or your AI agent shells out to gh.

8. Verify it, properly

Do not trust "it didn't error".

Check what actually goes over the wire.

# Which account does each tree authenticate as?
ssh -T git@github.com                          # -> Hi personal-user!
ssh -F ~/.ssh/config-work -T git@github.com    # -> Hi work-user!

# Which identity does each repo resolve to?
git -C ~/dev/work/some-repo config user.email  # -> work@example.com
git -C ~/code/personal-thing config user.email # -> personal@example.com

Run that inside an actual repo, and nowhere else. This is the one verification step that lies to you.

gitdir: matches the location of a .git directory. If there isn't one, there is nothing to match, and git quietly falls back to your global identity:

$ cd ~/dev/work && git config user.email      # the work folder itself
personal@example.com                          # looks broken, is fine

$ cd ~/dev/work/some-repo && git config user.email
work@example.com                              # the real answer

The top-level folder of your work tree is usually just a container, not a repo. Check it there and you will conclude the whole setup failed. git init a throwaway repo inside instead.

# Which key is actually OFFERED? This is the real test.
ssh -F ~/.ssh/config-work -v -T git@github.com 2>&1 | grep 'Offering public key'

You want exactly ONE line there, naming the work key. If you see two, IdentitiesOnly is missing somewhere.

# Real write access, without changing anything on the server.
git -C ~/dev/work/some-repo push --dry-run origin HEAD

# gh follows the folder?
(cd ~/dev/work && gh api user --jq .login)   # -> work-user
(cd ~ && gh api user --jq .login)            # -> personal-user

And a signing check, in a throwaway repo inside the work tree:

mkdir -p ~/dev/work/tmp-check && cd ~/dev/work/tmp-check
git init -q && git commit -q --allow-empty -m "check"
git log -1 --format='%an <%ae> sig:%G?'
# -> Your Name <work@example.com> sig:G
cd .. && rm -rf tmp-check

sig:G means good signature. sig:N means not signed. Anything else, something's off.

Can an agent just do part 1 for me?

It can. Paste this into Claude Code, Codex, or whatever you use. It's written so the agent verifies things instead of assuming them.

Set up two GitHub accounts on this machine, scoped by folder. I want a default
account, plus a second account that automatically takes over for every repo
under one specific folder. No manual switching, ever.

Ask me for these first, then do the work:
  - default GitHub username + email
  - second GitHub username + email
  - the absolute path of the folder that belongs to the second account

Configure all three layers so they agree:

1. IDENTITY. In ~/.gitconfig set the default user.name/user.email. At the very
   BOTTOM of the file add an includeIf with a "gitdir:" condition pointing at
   the folder (absolute path, trailing slash) and loading a .gitconfig-work
   file inside it, which overrides user.email.

2. TRANSPORT. Generate a separate ed25519 key per account if they do not exist.
   In ~/.ssh/config pin the default key to Host github.com and include
   "IdentitiesOnly yes". Then create a SEPARATE file ~/.ssh/config-work that
   also declares Host github.com but points at the second key, again with
   IdentitiesOnly yes. In .gitconfig-work set:
       core.sshCommand = ssh -F /absolute/path/to/.ssh/config-work
   Do NOT try to solve this with url.insteadOf rewriting and do NOT try to
   solve it with "ssh -i". Both silently fail. Verify why before trusting it:
     - insteadOf rules do not chain, and when two rules match the same prefix
       length the global one wins, so an https:// remote inside the work tree
       still resolves to the default key.
     - "ssh -i key" does NOT override IdentityFile from ssh_config, they are
       additive and the config entry gets offered first.
   Prove both of these on this machine and show me the output.

3. SIGNING. In .gitconfig-work use SSH signing (gpg.format = ssh,
   user.signingkey = the work .pub, commit.gpgsign = true) so the signing
   identity matches the commit identity. Set gpg.ssh.allowedSignersFile
   globally and write the allowed_signers entry. Then TELL me to add that
   public key to the second GitHub account a second time with key type
   "Signing Key" (not just Authentication), and check via
   https://api.github.com/users/USERNAME/ssh_signing_keys whether it landed.

4. gh CLI. Log in to both accounts. Note that `gh auth login` has NO --user
   flag, so the account is chosen by whoever is signed in in the browser
   during the flow. Tell me to use a private window for the second one. Then
   install a wrapper script on PATH (before
   the real gh) that picks the account per invocation: if the working directory
   is inside the work folder, or an explicitly named repo owner belongs to the
   work account, run the real gh with GH_TOKEN set from
   `gh auth token -u WORK_USER`. Exclude `gh auth ...` from the wrapper. Never
   call `gh auth switch`, the globally active account must stay untouched.

Also check ~/.git-credentials. If a bare `[credential] helper = store` exists,
it will silently copy tokens out of the keyring into a plaintext file. Scope it
away from github.com and tell me if a stale token is sitting there.

Back up every file you touch before editing, and tell me where the backups are.

Then VERIFY and show me the output of each, do not just tell me it worked:
  - ssh -T git@github.com, and with -F the work config, showing two different
    "Hi <user>!" responses
  - `ssh -v ... | grep 'Offering public key'` for both, proving exactly ONE key
    is offered in each case
  - git config user.email resolved inside and outside the folder, checked
    INSIDE A REAL REPO in each case (includeIf "gitdir:" matches the location
    of a .git directory, so in a bare folder it silently reports the global
    identity and looks like a failure)
  - git push --dry-run against a real repo in each tree
  - gh api user --jq .login from inside and outside the folder
  - a signed test commit in a throwaway repo inside the work tree, showing
    sig:G and the correct author email, then delete it
  - that look-alike sibling folders (e.g. the folder name plus a suffix) do NOT
    inherit the work identity

Report anything that does not pass instead of glossing over it.

How do you add a third account?

Once you have the pattern, another account is mechanical. Say a second client, client-user, living in ~/dev/client.

Four steps. All of them copies of what you already have.

1. A key.

ssh-keygen -t ed25519 -C "client@example.com" -f ~/.ssh/id_ed25519_client

Add your public key to that GitHub account twice: once as Authentication, once as Signing Key.

2. An SSH config for it. ~/.ssh/config-client:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_client
  IdentitiesOnly yes

3. A git config for it. ~/dev/client/.gitconfig-client:

[user]
	name = Your Name
	email = client@example.com
[core]
	sshCommand = ssh -F /home/you/.ssh/config-client
[gpg]
	format = ssh
[user]
	signingkey = /home/you/.ssh/id_ed25519_client.pub
[commit]
	gpgsign = true
[tag]
	gpgsign = true

4. One more includeIf, appended to ~/.gitconfig after the existing one:

[includeIf "gitdir:/home/you/dev/client/"]
	path = /home/you/dev/client/.gitconfig-client

Does the order matter? Only if the folders are nested. Last match wins. If they're siblings, order is irrelevant.

Then add the account to the gh wrapper. With three accounts a lookup table reads better than a chain of ifs:

#!/bin/bash
GH_BIN=/usr/bin/gh

# One row per NON-default account:  <gh-account>:<tree>:<owners-regex>
# The default account is deliberately absent. It is whatever `gh` has active
# when no row matches.
ACCOUNTS=(
  "work-user:$HOME/dev/work:work-user|SomeWorkOrg"
  "client-user:$HOME/dev/client:client-user|ClientOrg"
)

account=""
best=0
cwd="$(pwd -P)/"

for row in "${ACCOUNTS[@]}"; do
    acct="${row%%:*}"; rest="${row#*:}"
    tree="${rest%%:*}"; owners="${rest#*:}"

    # LONGEST matching tree wins, so a nested folder beats the one it sits in.
    if [[ "$cwd" == "$tree/"* && ${#tree} -gt $best ]]; then
        account="$acct"; best=${#tree}
    fi
    # An explicitly named owner outranks the folder rule.
    if [[ $* =~ (^|[[:space:]=/])($owners)/ ]] || [[ $GH_REPO =~ ^($owners)/ ]]; then
        account="$acct"; best=9999
    fi
done

if [[ -n "$account" && "$1" != "auth" ]]; then
    token=$("$GH_BIN" auth token -u "$account" 2>/dev/null)
    if [[ -n "$token" ]]; then
        GH_TOKEN="$token" exec "$GH_BIN" "$@"
    fi
    echo "gh: no stored token for $account" >&2
    echo "gh: run \`gh auth login\` and authenticate as $account" >&2
fi

exec "$GH_BIN" "$@"

Why a loop and not a case statement? Because case is first-match-wins, and the includeIf rule one section above is last-match-wins. List your accounts in the same order in both places and nested folders resolve to opposite accounts:

case "$CWD" in
  "$HOME/dev/work/"*)        account=work-user ;;
  "$HOME/dev/work/client/"*) account=client-user ;;   # never reached
esac

cwd = ~/dev/work/client/repo  ->  work-user      (git says client-user)

Ranking by the length of the matching tree makes the wrapper agree with git instead of quietly disagreeing with it.

Don't forget gh auth login for the new account. Otherwise the wrapper finds no token and quietly falls through to your default.

That failure is silent. Which is exactly why the version back in part 1 prints a warning.

And then immediately switch back:

gh auth switch -u personal-user

Adding a third account makes this worse than it was with two, because now the login you just did leaves the newest account as the global default for every unscoped folder you own. Check all of your trees, not just the new one:

for d in ~/code/personal-thing ~/dev/work/some-repo ~/dev/client/some-repo; do
  printf '%-32s %s\n' "$d" "$(cd "$d" && gh api user --jq .login)"
done

Three different answers, each matching the folder. If they are all the same, your wrapper is not being reached at all. Check that ~/.local/bin really comes before /usr/bin:

echo "$PATH" | tr ':' '\n' | grep -n -E '^(.*/\.local/bin|/usr/bin)$'

Can an agent do part 2 too?

This machine already has multi-account GitHub set up: a default account, plus
per-folder overrides driven by "includeIf gitdir:" entries in ~/.gitconfig,
each loading a .gitconfig-NAME that sets user.email and
core.sshCommand = ssh -F ~/.ssh/config-NAME, plus a gh wrapper on PATH that
picks the account per invocation.

Read those existing files first and follow the pattern exactly. Do not
redesign it and do not touch the accounts that already work.

Add one more account. Ask me for:
  - the new GitHub username + email
  - the absolute path of the folder it should own
  - any GitHub org names belonging to it

Then:
  1. Generate ~/.ssh/id_ed25519_NEW if it does not exist, chmod 600.
  2. Create ~/.ssh/config-NEW declaring Host github.com with that key and
     IdentitiesOnly yes, chmod 600.
  3. Create the folder's .gitconfig-NEW with user.name/user.email,
     core.sshCommand pointing at config-NEW, and SSH commit signing
     (gpg.format = ssh, user.signingkey = the .pub, commit.gpgsign = true).
     Add the key to ~/.config/git/allowed_signers.
  4. Append one more includeIf to ~/.gitconfig. If the new folder is nested
     inside an existing scoped folder, place it AFTER that one, since last
     match wins. Say which case applies.
  5. Extend the gh wrapper with the new folder and its owners. Refactor to a
     lookup table if it is getting long, and rank directory matches by longest
     matching path, NOT with a `case` statement, which is first-match-wins and
     would disagree with git on nested folders. Keep the `gh auth` exclusion
     and keep the warning when no token is found.

Tell me to run `gh auth login` for the new account. There is no --user flag on
`gh auth login`, so warn me that the account is picked by whoever is signed in
in the browser, and that I should use a private window. Also tell me to add the
public key to that GitHub account TWICE: once as an Authentication key, once as
a Signing Key.

After I have logged in, remind me to run `gh auth switch -u DEFAULT_USER`.
`gh auth login` leaves the account it just logged in as globally ACTIVE, and
the wrapper falls through to the active account for every unscoped folder, so
until I switch back all of my default repos silently resolve to the new
account. Verify this by running `gh api user --jq .login` from EVERY tree,
including the ones you did not touch, not just the new one.

Back up what you edit. Then verify and show real output:
  - ssh -F ~/.ssh/config-NEW -T git@github.com returns the new username
  - `ssh -v ... | grep 'Offering public key'` shows exactly ONE key
  - git config user.email in the new folder, checked inside a REAL REPO (in a
    bare folder includeIf does not fire and you will get the global identity
    and a false negative), and confirm the PRE-EXISTING accounts still resolve
    correctly (regression check, this is the point)
  - gh api user --jq .login from the new folder and from the old ones
  - a signed empty commit in a throwaway repo in the new folder shows sig:G
    with the right email, then delete it

If I tell you the folder for an EXISTING account has moved, treat that as a
different job: the path is hardcoded in four places and a missing includeIf
path is silently ignored rather than erroring, so the tree just reverts to the
default identity. Update all four, then verify. The four are the includeIf
CONDITION and its path= line (both, in ~/.gitconfig), the .gitconfig-NAME file
itself which must move with the folder, the tree in the gh wrapper table, and
any comments naming the old path. Run this first and make sure it comes back
empty afterwards:
    grep -rn "OLD/PATH" ~/.gitconfig ~/.ssh/config-* ~/.local/bin/gh
~/.ssh/config-NAME and the keys are keyed on host and account, not directory,
so they do NOT need changing.

What if you move a scoped folder later?

You will. The folder that seemed right on day one ends up somewhere else, and the whole mechanism is keyed on an absolute path.

Nothing warns you. Git does not validate that an includeIf path exists, and a missing include is not an error, it is just skipped. So the tree silently reverts to your default identity and keeps committing.

There are four places holding that path, and you have to change all of them:

grep -rn "dev/work" ~/.gitconfig ~/.ssh/config-work ~/.local/bin/gh

~/.gitconfig, the includeIf condition and its path = line. Two edits on one stanza, and it is easy to change the condition and forget the path.
<new-folder>/.gitconfig-work, which has to physically move with the folder.
~/.local/bin/gh, the tree in the account table. Miss this one and git is right while gh is wrong, which is the most confusing possible state.
Any comments naming the old path. Cosmetic, but this is the file you will read in a year when something breaks.

Note what is NOT on that list: ~/.ssh/config-work and the keys. Those are keyed on host and account, not on a directory, so they survive a move untouched.

Then verify with a real repo in the new location, and confirm both layers agree:

mkdir -p ~/dev/newplace/tmp-check && cd ~/dev/newplace/tmp-check
git init -q && git commit -q --allow-empty -m check
git log -1 --format='%ae sig:%G?'      # -> work@example.com sig:G
gh api user --jq .login                # -> work-user
cd .. && rm -rf tmp-check

Both lines have to be right. Checking only the git one is how you end up with correctly-authored commits and a gh pr create that opens PRs as the wrong person.

What are the two traps?

Both of these look correct. Both are recommended all over the internet. Both silently do the wrong thing.

I only found them because I tested the output instead of trusting the config.

Trap 1: why don't `insteadOf` rewrites chain?

The classic advice for this problem is a fake SSH host alias plus URL rewriting:

Host github.com-work
  HostName github.com
  IdentityFile ~/.ssh/id_ed25519_work

[url "git@github.com-work:"]
	insteadOf = git@github.com:

That works for git@ remotes. It does not work for https:// remotes.

And here's the thing. It fails quietly.

If you also have the common global rewrite https://github.com/ to git@github.com:, then inside your work folder an https remote gets rewritten once, to git@github.com:, and stops. Git does not run the rewrite a second time to catch the work rule.

So it goes out on your personal key.

You'd think adding an https:// rule to the work config would fix it. It doesn't. Both rules match the same prefix, and on a tie the global one wins:

inside the work folder:
  https://github.com/Org/repo.git  ->  git@github.com:Org/repo.git   (personal key)

Piling more rules into the work file won't save you either, because you can't make your rule more specific. The owner varies.

Trap 2: why doesn't `ssh -i` override `ssh_config`?

So your next idea is to skip URL rewriting entirely and just force the key:

[core]
	sshCommand = ssh -i ~/.ssh/id_ed25519_work -o IdentitiesOnly=yes

Looks bulletproof, right?

It is not. -i and IdentityFile from ssh_config are additive, not overriding, and the config entry gets offered first:

$ ssh -i ~/.ssh/id_ed25519_work -o IdentitiesOnly=yes -T git@github.com
Hi personal-user!

Read that again. You explicitly passed the work key, with IdentitiesOnly, and you got the personal account.

-F is the ONLY flag that's actually authoritative, because it replaces the config file rather than adding to it:

$ ssh -F ~/.ssh/config-work -T git@github.com
Hi work-user!

That's why the setup above uses a whole second SSH config file instead of a one-line flag. It's slightly more machinery.

It's also the difference between working and appearing to work.

What is that token doing in `.git-credentials`?

Go look at this file:

cat ~/.git-credentials

If you find a GitHub token sitting in there, it probably arrived by accident.

Git's credential protocol runs every configured helper. When one of them answers successfully, git then calls store on the rest of the chain. So if you have a bare [credential] helper = store sitting alongside the gh credential helper, store will faithfully copy gh's OAuth token out of your keyring and write it into a plaintext file in your home directory.

Nobody chose that. It just happens.

Why care, in a multi-account setup? Two reasons. It's a plaintext credential, often world readable. And it's ONE account's token being handed out for whatever host matches, which is precisely the cross-contamination you're trying to prevent.

If you follow the setup above, all your GitHub traffic goes over SSH and that file is never consulted for github.com. Still worth cleaning up.

Find out whether a bare store is in the chain:

git config --global --get-regexp '^credential'

A line reading credential.helper store, with no host in the key, is the problem one. It applies to every host. Drop it, and re-add store scoped to only the host that genuinely needs it:

git config --global --unset-all credential.helper
git config --global --add credential.https://gitlab.com.helper store

Then delete any stale github.com line out of the file itself, and lock it down:

sed -i '/github\.com/d' ~/.git-credentials
chmod 600 ~/.git-credentials

What you want to end up with is host-scoped helpers only:

credential.https://github.com.helper  !/usr/bin/gh auth git-credential
credential.https://gitlab.com.helper  store

So what do you actually get?

git clone a work repo into the work folder, and it just works. Right identity, right key, verified signature.
gh pr create in a work repo opens the PR as your work self.
Your personal repos are completely untouched by any of it.
Nothing to switch, so nothing to forget to switch back.

The whole thing is five files and about sixty lines.

In short: the config was the easy part. Most of the work was finding out that the two most-recommended approaches don't actually work.

Resources

https://git-scm.com/docs/git-config#_conditional_includes - the includeIf docs, including gitdir matching rules
https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtinsteadOf - insteadOf, and the "longest match wins" rule that causes trap 1
https://man.openbsd.org/ssh_config - IdentityFile and IdentitiesOnly, worth reading the exact wording on additive behaviour
https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification - why Authentication and Signing keys are different things
https://cli.github.com/manual/gh_auth_switch - the official multi-account story for gh, if you'd rather switch than wrap

Set it up once and stop thinking about it. Ganbatte!

I Tried to Make AI Output World-Class. Here's What Actually Happened.

2026-04-09T00:00:00+00:00

A multi-day experiment in context engineering, multi-agent pipelines, and the gap between "good enough" and genuinely excellent AI output.

TL;DR: I spent ~$5 and 500+ LLM calls trying to systematically push AI output from good to world-class across three domains. The most humbling finding: my hand-built debugging knowledge base made the model worse at debugging. It already knew more than I was teaching it. For landing page copy, no single prompt won everywhere. The trick was routing, picking the right strategy for each visitor type. For UI design, iterative revision improved individual elements but couldn't crack visual coherence without a design system defined upfront. The thread connecting all three: a weaker model with the right setup beat a stronger model with the wrong one.

The Question

It started with a landing page CTA.

I was building Menu Decoder (link opens in a new window), a travel app that helps people with dietary restrictions navigate foreign menus. I asked Claude to write the copy. It produced:

Ready to get started? Try the app and see what it can do for you. Try Menu Decoder

This is technically fine. It is also completely useless. It could be the CTA for a weather app, a recipe tool, a budgeting spreadsheet. It has no relationship to the specific fear a person with a peanut allergy feels when staring at a Thai menu they can't read.

I asked Claude to try again, this time focused on what the app actually solves. It produced:

Scan any menu. Know what's safe. Point your camera at a foreign menu and get instant allergen alerts in your language. Scan a Menu Now

Better. Obviously better. But I hadn't changed the model or the context. I had just given it better direction. Which raised the question that consumed the next several days:

Is there a systematic process for making AI produce genuinely excellent output? Or does it always require a human expert to point it in the right direction?

The Hypothesis

My initial assumption was straightforward: LLMs are generalists. They know a lot but not deeply. The path to world-class output should look something like how humans become world-class experts. Acquire deep domain knowledge, develop judgment, apply it to specific problems.

So I set out to build what I called a "latent space activator," a framework that would, through careful context engineering, transform a generalist LLM into a domain expert capable of producing top 1% output.

I started with code debugging, then landing page copy, then UI design. The experiment ran for several days, 500+ LLM calls, and cost roughly $15 in API fees.

The results were not what I expected.

Experiment 1: Code Debugging

Why This Domain

Code debugging has a property that makes it ideal for experimentation: ground truth exists and is unambiguous. Code either runs or it doesn't. A bug is either fixed or it isn't. You don't need human judges or conversion metrics. You need a terminal.

I built a three-layer pipeline:

Knowledge Base: four markdown files encoding debugging expertise from first principles. What a bug actually is (a divergence between mental model and system reality), eight root cause classes with correct and incorrect fixes, anti-patterns, decision trees.
Latent Space Activator: a system prompt that encoded not just knowledge but reasoning process. Classify before diagnosing, form falsifiable hypotheses, reason from invariants not symptoms.
Multi-Agent Pipeline: Generator produces a diagnosis, Critic adversarially challenges it, Arbitrator resolves the dispute. The theory was that adversarial review would improve output quality.

I tested this against eight code problems (quadratic complexity bugs, mutable default arguments, race conditions, closure capture issues) across four models and four configurations, 356 runs total.

What the Data Said

The first surprise: the knowledge base made things worse.

Config	Expert Rate
Bare model (no KB, no agents)	92%
KB only	85%
Full pipeline (KB + agents)	93%

The bare model outperformed the KB-only configuration. Adding carefully crafted expert knowledge about debugging made the model worse at debugging than it was without any help.

The explanation, once visible, was obvious: the model already had this knowledge. It had been trained on every debugging tutorial, every Stack Overflow answer, every textbook on algorithms. The KB didn't add knowledge. It competed with knowledge the model already held, in a slightly different vocabulary, producing interference.

The second surprise: all models, all configurations, all eight problems produced a 100% code execution pass rate. The problems were solved correctly every time regardless of architecture. The domain was simply within the native capability of current models.

The Real Finding

The original hypothesis, that architecture could substitute for model quality, couldn't be tested here because there was no gap to close. Current frontier models solve production-grade debugging problems reliably without any help.

The finding that mattered: KB scaffolding is net-negative when the model already has the expertise. You can't improve on what's already there by telling it how to think. You can only interfere.

Experiment 2: Landing Page Copy

A Different Kind of Problem

Landing page copy has a property that makes it structurally different from code: the ground truth is slow (conversion rates take weeks to measure), subjective (what's world-class for B2B SaaS isn't world-class for consumer fintech), and contested (experts disagree).

Instead of A/B testing, I built a judge. An LLM scoring output on five dimensions:

Visitor emotional accuracy: does the copy name the actual fear the visitor arrives with?
Specificity: is this copy specific to this product, or could it be any competitor's?
Mechanism clarity: does the visitor understand HOW the product solves the problem?
CTA-awareness match: does the call to action ask for the right level of commitment?
Interchangeability: could this copy be used by a competitor unchanged?

Six products, four configurations, 30+ runs. Products included Moz, Crazy Egg, GoHenry, Smart Insights, Sunshine.co.uk, and Course Hero, all drawn from documented conversion case studies with real lift numbers, not taste-based selection.

The Routing Discovery

No single configuration won across all products. But a clear pattern emerged when I sorted by visitor awareness level:

Cold traffic (visitor doesn't know the product exists): question_first won by a significant margin. GoHenry, a fintech product for children marketed to anxious parents via social media, scored 7.4 with question_first vs 6.2 bare. Forcing the model to articulate the visitor's emotional state before writing produced copy that named the specific tension parents feel: wanting their children to develop real financial skills while being terrified of real financial exposure.

"Give Your Child Real-World Money Skills, Without Real-World Risks."

That headline emerged from question_first. Bare generated: "Introducing GoHenry: The Smart Way to Teach Kids About Money."

Hot traffic (visitor ready to buy): bare won. Sunshine.co.uk, a budget travel site where the conversion barrier was skepticism about prices that seemed too good to be true, scored 7.4 bare and 6.0 with question_first. The visitor already knows what they want. Emotional probing adds noise. Specifics close.

Products with rational barriers (value vs free alternatives): mechanism_first was the critical intervention. Smart Insights, a digital marketing education platform competing against free content, went from 5.4 GENERIC with question_first to 7.2 COMPETENT with mechanism_first. The key sentence that appeared: "Get the depth of a marketing consultant at a fraction of the cost." That's the mechanism. It reframes the product from "another education platform" to "consultant alternative."

The Ceiling

Nothing broke 8.0. The best generated copy scored 8.4, and that was on my actual product, Menu Decoder, using the routed pipeline with Sonnet + mechanism_first.

"AI that reads what's not on the menu"

Snap a photo of any foreign-language menu and get instant safety alerts, even for hidden ingredients never listed on the page.

The judge gave this 9/10 for visitor emotional accuracy, 9/10 for specificity, 9/10 for interchangeability. The one weak score: 7/10 for CTA-awareness match, because the copy asks cold traffic to buy immediately without a lower-commitment first step.

The judge was right. The copy earned the click. The product flow has to earn the conversion. Copy can't fix a paywall that asks too much.

The Key Insight

The most important finding from the copy experiment wasn't about prompts. It was about the relationship between model quality and architecture value:

Running the same pipeline on Sonnet vs Gemini Flash showed that the interaction between model and configuration matters more than either alone. Sonnet with kb_scaffold produced WORLD_CLASS copy for Course Hero. Sonnet with bare produced worse copy than Gemini Flash with bare on Sunshine. A better model with the wrong configuration underperforms a weaker model with the right one.

Experiment 3: UI Design

The Setup

Default Claude Code UI output is competent and consistent. It is also visually identical across every project. Tailwind cards with shadow-md, blue-500 accent color, rounded-xl on everything. You can tell it's AI-generated not because it's bad but because it has no identity.

I wanted to know: can context engineering produce genuinely distinctive UI design? Or is the generic aesthetic a hard ceiling?

I built a pipeline that rendered generated Astro components in a browser using a Vite dev server, took Playwright screenshots, and evaluated them with a multimodal judge receiving the actual rendered screenshot.

The test case: Menu Decoder's main scan screen. Camera viewfinder, dish list with safety badges, FAB.

Test 1: What Activates Better Design

Four conditions, same functional spec, one variable changed per condition:

bare: White background, rounded cards, blue FAB, small pill badges. Classic default Tailwind. Shadow count: 2. Blue/indigo count: 2.

product_context: Describe the user's emotional state. Anxious traveler, dietary restriction, foreign restaurant. Visual output: identical to bare. Zero change. Describing the user does not activate visual capability.

reference_style: Specify the aesthetic target. Dark background, no shadows, no blue, Linear/Vercel aesthetic. Shadow count: 0. Blue/indigo count: 0. Dark background, translucent badge fills, sharp corners. A completely different design language activated by three sentences of style direction.

full_brief: Product context + style direction + explicit anti-patterns. The standout difference from reference_style: solid full-height color blocks for safety badges (bright green, amber, red) filling the right side of each dish row. The design comment at the top of the generated file read: "The safety badge must be the dominant visual element in each row." It was executed.

bare

reference_style

full_brief

The activating variable is visual style direction, not product understanding. Telling the model what the user feels does nothing. Telling the model what the screen should look like does everything.

Test 2: The Feedback Loop

I built an iterative revision loop: generate, screenshot, judge critique, revise, repeat twice. The judge was given the rendered screenshot and asked to identify the most important thing to fix, with a specific implementation instruction.

The revision instructions were excellent:

"Move the SCAN MENU button from its current centered bottom position to a fixed position at the bottom of the viewfinder area. The dish list must never be obscured by interactive elements."

"Replace small right-aligned pill badges with full-height color blocks that fill the entire right portion of each dish row. Apply the safety color to a div with absolute right-0 top-0 h-full w-20 containing centered white text."

The model executed both instructions. The layout improved measurably. And then something interesting happened: the visual coherence degraded. Locally correct decisions (FAB moved up, badges widened) produced a globally incoherent layout. A card container appeared around the dish list for no clear reason. The viewfinder got compressed awkwardly. The design started to feel assembled from competing decisions rather than designed from a unified logic.

Pass 0: initial

Pass 1: fixes applied

Pass 2: coherence lost

The score went from 5.2 to 6.4 and then stopped moving.

The Structural Finding

The revision loop worked at the element level and failed at the system level. Which revealed the real problem: there is no design system.

Every world-class product UI is built on a design system. Color tokens named by function, a typographic scale, a spacing unit, a component language. A designer doesn't design a screen; they define a system and then apply it.

The model is being asked to simultaneously define a design system and build a screen. Under that cognitive load, it defaults to its training distribution: Tailwind defaults. The revision loop makes individual decisions more correct without ever establishing the system that would make them coherent.

The correct pipeline architecture, not yet built but clearly indicated by the evidence, is:

Phase 1 (once per brand): Given a product brief, generate a design system specification. Color tokens. Type scale. Spacing unit. Component language. One sentence describing the visual identity.

Phase 2 (per screen): Given the design system spec + functional spec, build the screen. Every decision references the spec.

Phase 3: One targeted revision pass. Screenshot, specific instruction, revise once.

What Three Experiments Actually Proved

Finding 1: The assumption was wrong

The original hypothesis, that LLMs need to be taught domain expertise through context engineering, is wrong for well-covered domains. Current models already have world-class expertise in code debugging encoded in their weights. The architecture added nothing and sometimes subtracted.

The corrected hypothesis: context engineering adds value where the model has genuine capability gaps, not where it has latent expertise being suppressed. The KB helped weaker models on specific problem types. It hurt stronger models on problems they already understood.

Finding 2: The expert's attempt to help can make things worse

The KB was built by someone reasoning carefully about debugging expertise. It made outputs worse. The model's native representation of the domain was better than the expert's explicit encoding of it.

This has an uncomfortable implication: a domain expert trying to engineer the model's context might systematically underperform a non-expert who just asks the model directly. The expert's mental model competes with the model's better one.

Finding 3: Routing beats universal optimization

There is no single best configuration across domains. question_first wins for cold traffic. bare wins for hot traffic. mechanism_first wins for rational barriers. few_shot wins for warm traffic with pattern-matchable products.

The pipeline that produces consistent excellence isn't a better universal prompt. It's a routing layer that selects the right intervention for the specific problem type. Classification before generation.

Finding 4: Architecture value is inversely proportional to model capability

This appeared in both the code and copy experiments. For the cheapest model, the architecture added 6+ percentage points of expert rate. For the frontier model, it added nothing or hurt.

The window in which "use a better prompt" beats "use a better model" is shrinking as inference costs drop. This doesn't mean prompting is useless. It means the ROI calculation changes, and the engineering cost of maintaining a complex pipeline should be weighed against the cost of upgrading the model.

Finding 5: The generation/revision loop is necessary but not sufficient for UI

Copy can be world-class in a single generation pass with the right activation. UI design cannot, because world-class UI requires a coherent system applied consistently, and single-pass generation under prompt pressure defaults to assembling from framework defaults rather than designing from first principles.

The iterative revision loop improves individual elements. It doesn't establish the system. A design system definition phase, before any screen is generated, is the missing step.

What I'm Building Next

The routing pipeline for landing copy is in production. Menu Decoder's landing page uses the output. The headline, "AI that reads what's not on the menu," came from this experiment.

The UI design pipeline needs the design system layer before it's useful. That's the next experiment, and it'll be driven by an actual deliverable: Menu Decoder needs a full UI, not just a test screen.

The code debugging findings have a different application: they suggest that for domains where models already have strong priors, the most valuable architectural contribution isn't a KB or a multi-agent pipeline. It's a selective reliability mechanism. A fast, cheap check that identifies the small percentage of generations that are genuinely uncertain, and applies review only there. Most generations don't need it. Some do. Knowing which is which is the real engineering challenge.

The total cost to run all experiments described in this post: $15 in API fees and 8 hours of compute time across several days of iteration.

The most expensive insight: sometimes the best thing you can do is get out of the way.

Built with Claude Code, OpenRouter, Bun, and Astro. Experiments run on Gemini Flash 2.0, DeepSeek R1, Qwen3 Coder, and Claude Sonnet 4.5.

The Optimal Tech Stack, Architecture, and DevOps Setup for Building with Claude Code

2026-04-01T00:00:00+00:00

A first-principles analysis of how to structure your codebase, not for humans, but for an AI agent.

Most advice about AI coding tools tells you the same thing: use the most popular framework. More Stack Overflow answers, better AI output.

That intuition is roughly right. It is also incomplete.

When you are building with Claude Code specifically, the agent is not just generating code from memory. It is navigating your codebase, reading files, running tools, and working inside a fixed context window.

Your codebase structure affects the quality of every edit it makes.

So this post is not about best practices. It is about optimizing for how Claude Code actually works, from first principles and from what the leaked Claude Code source confirmed about its internal mechanics.

Tl,dr:

Claude Code navigates your codebase via grep and surgical string replacement. It does not read everything.
Fewer files means less token overhead, which means more context left for actual logic.
TypeScript strict mode. Astro + Vue + Tailwind on the frontend. Hono + Bun + Drizzle on the backend. One file per feature slice. systemd + Caddy on a plain VPS.
It all falls out of two principles: full context in one load, and types as prediction constraints.

How does Claude Code actually work?

Before you decide anything about architecture, you need to know what Claude Code is doing under the hood.

It is not a chatbot that reads your whole codebase.

It is an agent with a set of tools: file read, bash, grep, string replacement, LSP. It uses them to navigate your project and make surgical edits. Every tool call costs tokens. Every file it reads takes up space in a context window.

And the part that matters most: the quality of its output DEGRADES as your context window fills up.

The leaked source confirmed a few specific mechanics. Each one should change how you structure your code.

It uses str_replace, not full rewrites. The primary edit tool finds a unique string in your file and replaces it.

Which means it fails on ambiguous patterns. If the same code block appears twice in a file, the edit becomes unpredictable. File size matters less than pattern uniqueness within a file.

It greps, it does not read. Rather than loading every one of your files in full, Claude Code uses a dedicated Grep tool to locate the relevant code before reading it. A well-structured, clearly named codebase is easier to grep than a clever, abstract one.

It has a three-layer memory system. A lightweight MEMORY.md index of pointers, on-demand topic files, and grepped identifiers from transcripts. Your raw files are never fully re-read into context, they get fetched on demand.

So co-located context beats scattered context. Every time.

The context window is around 180k usable tokens. The system prompt, tool definitions and memory files eat roughly 20k of that before you write a single line of code. At approximately 4 characters per token, your practical working budget for code is around 140,000 to 160,000 characters per session.

That is the whole budget.

Autocompaction triggers at a ~13k token buffer. When your context fills, Claude Code compresses conversation history and re-injects recently accessed files at 5,000 tokens each. Files it has not touched recently are dropped.

So co-locating your files is a performance concern. Not an aesthetic one.

First principle: why does information density matter?

The single most important optimization you can make is maximizing the ratio of relevant logic to total tokens consumed.

Every import statement, config file header, re-exported type and boilerplate comment is a token that contributes no logic. In a multi-file architecture you pay that cost again and again.

In a single file you pay it once.

Which is why the conventional "one file per component" rule hurts you here. That rule exists entirely for human navigation.

Claude Code does not navigate a directory tree the way you do. It pays a tool call cost to open each file.

Fewer files, fewer tool calls, more of your context window occupied by actual logic.

So what is the stack?

TypeScript: why strict mode, no exceptions?

Strict mode is not just good practice here. It mechanically improves Claude's output quality.

Why? Because when Claude generates the next token in a sequence, your types constrain the probability space of what it can generate. A typed interface makes hallucinating a wrong method name significantly less likely, because the correct token has higher probability given the surrounding context.

More types, better output. Not because of convention. That is just how prediction works.

Practical rules:

strict: true in tsconfig
Explicit return types on all functions
No any, ever
Zod schemas for all runtime validation, co-located with the types they validate

Frontend: why Astro + Vue + Tailwind?

Astro handles your static/dynamic split cleanly. Static marketing pages are generated at build time. Interactive app components mount as Vue islands with client:only="vue".

One project, one build command, one output folder. Claude never has to reason about two separate frontend deployments.

Vue SFCs are naturally Claude-friendly, because each of your .vue files is already a cohesion unit. Template, script and style are co-located.

That matches how Claude Code loads context. One file load gives Claude everything it needs to understand and edit that component.

Tailwind is mechanically optimal for AI generation. Every class is atomic, explicit, and has appeared millions of times in training data.

Claude can predict flex items-center gap-4 with near certainty. It cannot do the same for your custom CSS class names. Eliminating CSS files removes an entire category of cross-file context lookups.

Never write a CSS file. Not even one.

Backend: why Hono + Bun + Drizzle + PostgreSQL?

Hono is TypeScript-first in a way that Express is not. Types flow through your request/response cycle explicitly:

// Express — Claude infers types at runtime
app.post('/api/users', async (req: Request, res: Response) => {

// Hono — types are explicit at the route definition
app.post('/api/users', zValidator('json', createUserSchema), async (c) => {
  const body = c.req.valid('json') // fully typed, no inference needed

This is not a style preference.

Explicit typing reduces the probability of Claude generating incorrect property accesses, wrong response shapes, and missed validation checks.

Bun as the runtime gives you native TypeScript execution (no build step), faster startup, and built-in APIs. It is stable for long-running HTTP servers.

Now you will say: didn't the leak report Bun memory leaks? It did. Those reports were specific to Bun running as a long-running CLI tool managing concurrent streams and subagents. A very different workload from an HTTP server.

Drizzle with a single schema.ts file is the most important database decision you can make for Claude Code.

When Claude reads one file and understands your entire data model, every table, every column, every relationship, it can generate correct queries, migrations and service logic without any additional context.

Scattered migrations, multiple schema files, runtime-inferred schemas: all of them require Claude to do additional work before it can reason about your data.

PostgreSQL, because it is the most thoroughly represented database in training data. Claude's Postgres knowledge is deep and reliable.

How should you lay out the codebase?

Which phase are you in?

The optimal architecture depends on which phase of development you are in. These are genuinely different, and applying the wrong one is costly.

Phase 1: MVP / one-shot generation

When you are building a new app from a spec, optimize for generation, not navigation. You want working code as fast as possible.

The optimal structure is one file. Or as few files as you can manage, grouped internally by feature with explicit section markers.

// ============================================================
// AUTH
// ============================================================

// ============================================================
// PAYMENTS
// ============================================================

// ============================================================
// DASHBOARD
// ============================================================

These markers are not just for human readability. Heading patterns like this appear frequently in training data as organizational markers, and they increase the probability that Claude correctly associates subsequent tokens with the right domain.

They are a prediction constraint.

The ceiling for this approach is around the Sonnet 4.6 output token limit of 64,000 tokens, which is enough for most non-trivial apps. For anything larger, use multiple files, but still group by feature rather than by technical layer.

Phase 2: iterative development

Once an MVP is validated and you are building features incrementally, switch to Vertical Slice Architecture.

The critical distinction from conventional VSA is that each slice is ONE FILE, not one directory. Everything your feature needs lives in a single file. Route, service logic, Zod validation, types.

src/features/
  auth.ts          ← Hono route + service logic + Zod schemas + types
  payments.ts      ← everything payments in one file
  dashboard.ts     ← everything dashboard in one file

Your Vue components follow the same principle, but naturally. Each .vue SFC is already a single-file cohesion unit containing template, script and style together.

Why does one file per slice beat one directory per slice? The same reason it beats layered architecture: one task touches one feature, one feature loads one file.

When Claude edits your auth logic, it reads auth.ts and has everything. The route definition, the validation schema, the service function, the types. A single context load.

With a directory-per-slice approach, Claude must open route.ts, grep for the service in service.ts, check the schema in schema.ts. Three tool calls before it has made a single edit.

The key constraint is pattern uniqueness, not file length. The str_replace tool fails when the same code pattern appears twice in the same file, not when files are long.

A 500-line file with clean, explicitly named, non-repeating code is better for Claude Code than five 100-line files with similar structure.

So split your slice into multiple files only when patterns within it start repeating. Not before.

Then add a single src/features/AI-CONTEXT.md describing the conventions for all your slices: what each file is responsible for, naming rules, how cross-slice dependencies are handled. Claude Code re-reads CLAUDE.md on every query iteration, and this file gives it the same benefit scoped to the features layer, without requiring a directory per feature.

What goes in the shared packages?

In a monorepo, the shared packages are the highest-leverage investment you can make for Claude Code quality:

packages/
  db/          # Drizzle schema — single source of truth for all DB types
  api-types/   # Zod schemas + response types shared between frontend and backend
  config/      # App constants and product config

When Claude reads packages/api-types/index.ts, it knows what every API endpoint accepts and returns. When it reads packages/db/schema.ts, it knows your entire data model.

Those two files give Claude more accurate context than any amount of inline documentation.

Never duplicate types between frontend and backend. Any type that exists in two places is a type that will eventually diverge, and a diverged type is a context that MISLEADS Claude.

What about DevOps?

Does the same principle apply to infrastructure?

It does. Claude Code manages your server through bash commands and file edits, so the optimal infrastructure is one where the entire running state of your system can be understood by reading a small number of declarative files.

Process management: why systemd over PM2?

PM2 stores your running state in memory. To understand what is running, Claude must execute pm2 list and parse table output. To understand how a service is configured, it must read a separate ecosystem config file.

The source of truth is split between runtime state and config files.

systemd is declarative. Every one of your services is a .service file, and the file IS the source of truth:

[Unit]
Description=myapp backend
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/myapp
EnvironmentFile=/home/deploy/myapp/.env
ExecStart=/usr/bin/bun run src/index.ts
Restart=always

[Install]
WantedBy=multi-user.target

Claude can read this file once and know exactly how your process runs. It can edit it directly.

systemctl status myapp gives structured, readable output. systemctl list-units --type=service gives Claude a complete picture of everything running on the server.

That is the declarative infrastructure principle applied to process management.

Reverse proxy: why Caddy?

Caddy over Nginx for one reason: your Caddyfile is readable in a single context load.

Your Nginx configuration sprawls across sites-available/, sites-enabled/, conf.d/, and include directives. Caddy's entire reverse proxy config for multiple projects fits in one file:

myapp.com {
  handle /api/* {
    reverse_proxy localhost:3000
  }
  handle {
    root * /var/www/myapp
    file_server
  }
}

TLS is automatic. No certbot, no renewal cron jobs, no certificate files to manage.

Hosting: why a VPS over a PaaS?

A single Hetzner VPS running 10 of your projects costs roughly the same per month as one project on a managed PaaS.

More importantly for Claude Code, a VPS is a stable, predictable environment. Claude's bash tool has a reliable surface to work with. There are no platform-specific CLI tools to install, no API keys for infrastructure management, and no vendor-specific configuration formats to learn.

The total infrastructure state of your multi-project VPS, from Claude's perspective, is:

/etc/systemd/system/*.service, all running processes
/etc/caddy/Caddyfile, all routing
~/shared-infra/SERVER.md, conventions and project list
Individual project .env files

Four categories of files. And Claude understands your entire server.

What is the SERVER.md for?

This is the most under-appreciated file in your entire setup.

Claude Code has no persistent memory of your server across sessions. Without a single reference file, it must infer conventions each time. How projects are named, how services are structured, where env files live, how to deploy a new project.

A ~/shared-infra/SERVER.md solves this:

# Server Overview

## Projects
| Project | Domain | Port | Systemd Service |
|---|---|---|---|
| myapp | myapp.com | 3000 | myapp.service |
| otherapp | otherapp.com | 3001 | otherapp.service |

## Conventions
- Projects live in ~/projects/{name}
- Systemd services: /etc/systemd/system/{name}.service
- Static files: /var/www/{name}/
- Env files: ~/projects/{name}/.env

## Adding a New Project
1. Clone repo to ~/projects/{name}
2. Copy .env.example to .env, fill values
3. Create systemd service file
4. Add Caddy block for domain
5. systemctl enable --now {name}

Claude reads this once per session and has your entire server mental model loaded.

CI/CD: how much do you need?

A single .github/workflows/deploy.yml that Claude can read and edit entirely in one context load:

typecheck → build frontend → SSH into VPS → pull → install → restart service

Nothing more for an MVP.

The feedback comes back as GitHub Actions log stdout, so Claude can read a failed workflow output and self-correct without any additional context.

What is the whole picture?

Every decision in this stack follows from the same two principles.

Principle 1: full context in one load. The best edit is the one where Claude has everything it needs in a single context load, with no grepping, no file navigation, no inference. That drives the monorepo with shared packages, feature-grouped files at MVP phase, Caddy over Nginx, systemd over PM2, and the SERVER.md.

Principle 2: types as prediction constraints. The more explicitly typed your code, the smaller the probability space of what Claude can generate next, and the less likely it is to hallucinate incorrect method names, wrong response shapes, or missing validation. That drives TypeScript strict mode everywhere, Zod for all validation, Drizzle schema as single source of truth, and Hono over Express.

Everything else follows.

Reference: the stack in one table

Concern	Choice	Reason
Language	TypeScript strict	Types constrain prediction
Frontend framework	Astro 5	Static/dynamic split, one build
UI framework	Vue 3 client:only	SFC = natural cohesion unit
Styling	Tailwind 4	Atomic, no CSS files
Data fetching	TanStack Query	Explicit state, well-represented
Backend framework	Hono	TypeScript-first, typed routes
Runtime	Bun	Native TS, fast
Validation	Zod 4	Runtime types, co-located
ORM	Drizzle	Single schema file
Database	PostgreSQL	Best training data coverage
Architecture (MVP)	Single file, grouped	Full context, one generation pass
Architecture (iterative)	Vertical slices	One task = one file = one load
Process manager	systemd	Declarative, file-based
Reverse proxy	Caddy	Single readable config file
Hosting	Hetzner VPS	Predictable, cheap, CLI-first
CI/CD	GitHub Actions + SSH	One workflow file, readable stdout

Frequently Asked Questions

Why Astro + Vue instead of Next.js + React?

Next.js and React are not wrong choices. They have enormous training data coverage and Claude handles them well.

The issue is architectural. Next.js blends server and client code in ways that create ambiguity for Claude. Server Components, Client Components, server actions and API routes all coexist in the same files with implicit boundaries, so Claude has to infer which execution context it is in before it can generate correct code.

Astro's static-only mode eliminates that ambiguity entirely. Static pages are static. Interactive components are explicitly marked client:only="vue". There is no blurred boundary.

Vue SFCs add another layer of clarity: template, script and style are co-located in one file, which is the single-file cohesion principle applied at the component level.

Already invested in Next.js and React? The architecture principles in this post still apply. Use strict TypeScript, co-locate related code, use Tailwind, keep shared types in one place.

The framework matters less than the structure.

Does this architecture work with React or other frontend frameworks?

Yes. The principles are framework-agnostic.

What matters is that your components are self-contained cohesion units (React .tsx files work fine for this), that you are not writing CSS files, and that you are not splitting code across layers for a single feature.

The specific recommendation of Vue + Astro comes from Vue SFCs being naturally single-file and from Astro's clean static/dynamic boundary. But a React developer can apply the same principles: one file per feature slice, Tailwind only, strict TypeScript, shared types package.

Should I use a single file for the entire backend even for a large app?

Only at the MVP phase, and only until you hit the output token ceiling. Sonnet 4.6 has a 64k output token limit, which is enough for most initial builds.

Once you are iterating on a validated product, switch to one file per feature slice: auth.ts, payments.ts, dashboard.ts. Each file contains its Hono route, service logic, Zod schemas, and types.

The goal is not to minimize file count forever. It is to make sure any single task Claude performs touches exactly one file. That is when context is most efficient.

What if I want to use Prisma instead of Drizzle?

Prisma and Drizzle serve the same purpose here: a single schema file that gives Claude your complete data model in one read. Prisma's schema.prisma is equally good for this.

The choice between them is largely a preference question. Drizzle has the slight edge because the schema is TypeScript, so types flow naturally into the rest of your codebase without a generation step.

But if you know Prisma well, the architectural benefit is identical.

Why a VPS over Railway, Fly.io, or Vercel?

For Claude Code specifically, the VPS wins because your entire infrastructure state lives in files Claude can read and edit directly. systemd service files, a Caddyfile, a SERVER.md.

On managed platforms, infrastructure state is split between a CLI, a dashboard, and platform-specific configuration formats. Claude cannot read a Railway dashboard. It can read /etc/systemd/system/myapp.service.

The cost argument is also real. A 4GB Hetzner VPS runs 10 of your projects for roughly the same monthly cost as one project on a managed PaaS.

That said, if you are deploying a single project and want zero server management, Railway or Fly.io are reasonable. The architecture and code structure recommendations in this post apply regardless of where you deploy.

Does this work for mobile apps too?

The backend and shared package principles apply directly. Hono as the API, Drizzle schema as the single source of truth, @repo/api-types shared between mobile and backend.

For the mobile layer, React Native and Expo are well-covered in training data and Claude handles them reliably.

The one-file-per-slice principle applies to React Native screens the same way it applies to Vue components. Each screen is a cohesion unit that should contain its own data fetching, local state and layout, without reaching into shared layer files for routine operations.

Happy shipping!

This analysis is based on first-principles reasoning about how LLMs operate, confirmed where possible against the Claude Code source code that was inadvertently leaked on March 31, 2026.

PostgreSQL Function Syntax: Demystifying Anonymous vs. Tagged Dollar-Quoting

2025-07-16T00:00:00+00:00

I am running my DB in Supabase, and one of the triggers that inserted an entry into the public table user_metadata on new user registration was broken and needed update:

create or replace function public.handle_new_user() returns trigger as $$
begin
  insert into public.user_metadata (user_id, plan_id)
  values (new.id);
  return new;
end;
$$ language plpgsql security definer;

This is the code I had in Supabase. The issue was that we pass plan_id, but user_metadata does not have such a column, so the trigger fails.

Supabase has an AI assistant that can fix these errors for you, writing new code. Well, it simply has to remove the plan_id, right? Well this is what it wrote:

CREATE OR REPLACE FUNCTION public.handle_new_user()
 RETURNS trigger
 LANGUAGE plpgsql
 SECURITY DEFINER
AS $function$
begin
  insert into public.user_metadata (user_id)
  values (new.id);
  return new;
end;
$function$;

Uh?? My first though was, what is this? On a closer inspection, there is nothing to be alarmed, because the only real change is indeed getting rid of that plan_id

But that forced me to actually read the code 😅

I have basic SQL knowledge so I had never seen this syntax before.

Let's review what changed piece by piece:

NUMBER 1

This

... language plpgsql security definer;

somehow moved before the inner function part

...
 LANGUAGE plpgsql
 SECURITY DEFINER
... the nested function

Oh... in SQL, clauses can switch places, it's ok. And, you know, the lowercase or uppercase for SQL syntax, it doesn't matter. SQL is not case sensitive.

So those two things are the same.

NUMBER 2

This

... as $$
begin
  ... thing broken ...
end;
$$

Changed to this

...
AS $function$
begin
  ... thing fixed ...
end;
$function$;

Uh? What is $$ and $function$ . I have never seen this. So it's time to learn some syntax.

They are both "dollar-quotings", and solve the same problem, namely:

Say, you're trying to write a SQL function. Let's do it step by step:

Step 1: scaffold the function

CREATE FUNCTION my_func() RETURNS text LANGUAGE plpgsql AS

Step 2: Put the meat in

CREATE FUNCTION my_func() RETURNS text LANGUAGE plpgsql AS '
begin
  -- a comment with apostrophe isn''t easy to write
  return ''Hello, World!''
end;

Obviously, this function is super simple. Notice the single quotes around the function. Why do we have them? Well... this is SQL for you. The function body must be a string, end of story.

This forces us to quote every actual single quote in the function body, that is annoying. Also, syntax highlighters will likely show the entire body as uniform yellow, hard to read.

Here is were DOLLAR-QUOTING enters the stage to solve all these problems.

It basically allows us to write the function like this:

CREATE FUNCTION my_func() RETURNS text LANGUAGE plpgsql AS $$
begin
  -- a comment with apostrophe isn't easy to write
  return 'Hello, World!'
end;
$$

See, no more duped single quotes, and we get a beautiful syntax highlighting.

Now you know what dollar-quoting is. But hold on. We have seen two different versions of dollar quoting: $$ and $function$ . Where do they differ?

$$: This is called anonymous dollar-quoting. It does exactly what we have seen it do right above. It helps us get rid of the single quotes around the function body.
$function$ : This is called Tagged Dollar-Quoting. And it does... it does the same! So, then what is the point? It is nesting. With anonymous dollar-quoting, you cannot nest them, because the second $$ will ALWAYS mark the end of the first $$

... let's nest'em ... AS $$
begin
  ... do something
  AS $$ <-- here we are trying to nest a second $$, but all SQL is seeing is the closing of the first $$ :_(
  begin <-- here SQL will show a syntax error!
    ... do something else <-- this will never run!
  end;
  $$
end;
$$

You see how that will break? We can't nest $$ !

But we can nest the tagged version!

... let's try again! ... AS $fnc_a$ <-- see we're using the tag!
begin
  ... do something
  AS $fnc_b$ <-- no tagging confusion here, we're good!
  begin 
    ... merry fucking xmas!! ...
  end;
  $fnc_b$ <-- and we close them
end;
$fnc_a$

Hopefully we are all clear about these little SQL syntax adventures

Go do some $rock_n_roll$ !

How to Make VS Code Search Find Specific Gitignored Files

2025-04-19T00:00:00+00:00

VS Code search usually hides files listed in your .gitignore. This is good for hiding things like node_modules.

But sometimes you need VS Code search (Ctrl+P or Ctrl+Shift+F) to find a specific file or folder that is in .gitignore.

Here's how to do it without changing your .gitignore file.

The Plan

Tell VS Code search to stop using the .gitignore file automatically.
Manually list only the files you still want hidden inside VS Code's settings.

This means any file not listed in the settings will show up in search, even if it's in .gitignore.

How to Do It

Use Workspace Settings. This keeps the changes only for your current project.

Open the Command Palette: Ctrl+Shift+P (or Cmd+Shift+P on Mac).
Search for and select Preferences: Open Workspace Settings (JSON).
This opens (or creates) a .vscode/settings.json file for your project.
Add or modify the settings like this:

{
  // 1. Stop VS Code search from using .gitignore
  "search.useIgnoreFiles": false,

  // 2. List ALL patterns you STILL want hidden from search results (Ctrl+Shift+F)
  "search.exclude": {
    // Default stuff you likely want hidden
    "**/node_modules": true,
    "**/bower_components": true,

    // Add other patterns FROM YOUR .gitignore that you want hidden
    // For example:
    "**/dist": true,
    "**/build": true,
    "**/*.log": true,
    "**/coverage": true,

    // --- IMPORTANT ---
    // DO NOT add the patterns you want VS Code TO FIND here.
    // Example: If you want 'docs/internal/**/*.md' to be searchable,
    // make sure it's NOT listed in this 'search.exclude' section.
    // Because 'search.useIgnoreFiles' is false, these files will now appear.
  },

  // 3. Optional: Control what's hidden in File Explorer and Ctrl+P Quick Open
  // You might want the same files hidden here as in 'search.exclude'.
  // If you want specific files visible in Ctrl+P, DO NOT list them here.
  "files.exclude": {
    "**/node_modules": true,
    "**/bower_components": true,
    "**/dist": true,
    "**/build": true,
    "**/*.log": true,
    "**/coverage": true

    // Again, DO NOT list patterns here that you want to find via Ctrl+P.
  }
}

Explanation

"search.useIgnoreFiles": false: Makes VS Code search ignore .gitignore.
"search.exclude": You must list everything you want hidden from Search Results (Ctrl+Shift+F). Copy patterns from .gitignore here (like node_modules). Do not list patterns you want to find.
"files.exclude" (Optional): Hides files from the File Explorer sidebar and affects Quick Open (Ctrl+P). Usually, keep it similar to search.exclude. Do not list patterns you want to find with Ctrl+P.

Downside

You now manage ignore rules in two places:

.gitignore (for Git).
.vscode/settings.json (for VS Code search/visibility).

If you update .gitignore, you might need to update search.exclude and files.exclude in VS Code settings too.

This setup gives you precise control over which ignored files show up in VS Code search.

Mastering React.useEffect for Optimal Component Behavior

2023-11-11T00:00:00+00:00

React's useEffect hook is a powerful tool for synchronizing your components with external systems. However, its misuse can lead to inefficient and error-prone code. Understanding when and how to use useEffect is crucial for crafting efficient React applications.

Understanding useEffect's Role

The Ideal Use of useEffect

useEffect is primarily designed to "step out" of the React paradigm and interact with external systems, such as APIs or subscriptions. Its most effective use cases include:

Executing logic when a component mounts or updates.
Synchronizing with external data sources or APIs.

Common Misuses of useEffect

React developers often fall into the trap of using useEffect for scenarios where it’s unnecessary:

React State Synchronization: If the goal is to sync React state, useEffect is likely overkill. Direct state management or context can often suffice.
Responding to User Actions: Instead of triggering effects in response to user actions, it's more efficient to handle these within event handlers directly.
Combining Unrelated Logic: Grouping unrelated logic in a single useEffect because they run at similar times can lead to tangled code. It's cleaner to use multiple useEffect instances for distinct tasks.

External Subscriptions and Fetch Requests

While useEffect can be used for subscribing to external sources, useSyncExternalStore offers a more robust solution. For data fetching, especially with potential race conditions, consider using libraries like TanStack Query or a suitable framework.

useEffect Dependencies: A Critical Consideration

Correctly managing useEffect dependencies ensures the effect syncs accurately with your component's lifecycle:

State Variables Only: Dependencies should typically be limited to state variables (state, props, computed values).
Avoid Non-Reactive Values: Mutable, non-reactive variables like location.pathname or ref.current should not be dependencies. Instead, use alternatives like useSyncExternalStore.

Linting and useEffect

React's linter warnings about missing dependencies in useEffect are often indicative of issues in the effect's implementation:

Never Suppress Linter Warnings: Ignoring these warnings can lead to subtle bugs.
Split Up Complex Effects: If an effect is doing too much, consider breaking it into smaller, more focused effects.
Be Cautious with Objects and Functions: Using these as dependencies can lead to unnecessary re-renders or stale closures.

Experimental: useEffectEvent

React's experimental useEffectEvent API offers a way to create effects that respond to reactive state changes without including the state in the dependency array:

const onVisit = useEffectEvent(visitedUrl => {
  logVisit(visitedUrl, numberOfItems);
});

useEffect(() => {
  setTimeout(() => {
    onVisit(url);
  }, 5000); // Delay logging visits
}, [url]);

Best Practices for useEffect

Declare Non-Reactive Variables Outside Components: This practice keeps your components clean and focused.
Naming Conventions: If a function doesn’t call hooks, avoid using the use prefix, as this is conventionally reserved for hooks.

Understanding and applying these principles will help you leverage useEffect effectively, leading to more maintainable and performant React applications.

References

React Documentation on Effects: React Docs: useEffect
Handling External Data Fetching: TanStack Query
Managing Dependencies in useEffect: React Docs: Effect Dependencies
React's useSyncExternalStore: React Docs: useSyncExternalStore
Experimental useEffectEvent: React Experimental useEffectEvent

Decoding Firestore's Cache Strategies

2023-06-06T00:00:00+00:00

I'll tell you what, I didn't know there was a Firestore's cache behavior out of the box. So I read about about it, and I want to share it, let's get right into it!

Exploring Firestore's Cache Strategies

Firestore gives us the power to configure cache behavior with a simple tool - GetOptions. In our toolbox, we've got three cache strategies.

Default: This little trooper attempts to fetch the latest data from the Firestore server. But, you know what? If it can't reach the server (because hey, things happen), it won't leave you hanging. It returns the data from the cache. Reliable, isn't it?
Server: The server strategy is a bit more, shall we say, focused. It only fetches from the Firestore server. If it can't reach the server, it throws in the towel. It's all or nothing with this one.
Cache: Lastly, we have the cache strategy. It only fetches from the cache and will accept defeat if the document isn't in the cache. It's got a one-track mind, but it sure is good at what it does.

Now, wouldn't it be fun to see this in action? Take a look at this code snippet:

import { getDoc, doc, getFirestore, GetOptions } from "firebase/firestore";

const db = getFirestore();
const docRef = doc(db, "collection", "documentId");

// Create a GetOptions object
const options: GetOptions = {
  source: "cache" // You can also use "default" or "server"
};

// Get the document, forcing the SDK to fetch from the cache.
getDoc(docRef, options).then((docSnapshot) => {
  if (docSnapshot.exists()) {
    console.log("Document data:", docSnapshot.data());
  } else {
    console.log("No such document!");
  }
}).catch((error) => {
  console.error("Error getting document:", error);
});

Decoding Stale Cache Data

Now, you might be wondering, "How does Firestore determine if cache data is stale or not?" Good question! Firestore doesn't give us explicit controls for this. Instead, it's always keeping our cache synchronized with the server whenever our network connection is on point.

Firestore tries its best to provide up-to-date results from the cache when you perform a query. But, if the required data is not available or if it thinks the cache data may be a bit behind the times (like, it's been awhile since the last synchronization), it'll attempt to fetch the fresh data from the server.

A Quick Note on Offline Persistence

Before we wrap up, let's not forget about offline persistence. Firestore offers offline support for mobile (iOS and Android) and web clients. Just remember, offline persistence is not a fan of Node.js client libraries - it's not supported there.

On Android and iOS, offline persistence is enabled by default (convenient, eh?), but on the web, it likes to be formally invited - you've got to enable it explicitly. Also, Firestore is a self-starter and manages the offline cache, including deleting older, unused data. But if you want to get your hands dirty, you can manually clear the cache.

For the finer details and limitations of Firestore offline persistence, you'd do well to refer to the official Firestore documentation.

Hope this helped!

TypeScript Object Types: Extracting Types from Keys and Values

2023-03-15T00:00:00+00:00

As a TypeScript developer, you'll often find yourself in situations where you need to extract the types of the keys and values from an object. Fortunately, TypeScript provides some utility types that can help you achieve this.

Say, you're building an app that needs to display some user information, and you have an object that contains all the user data. You need to extract specific types from this object, including the types of both the keys and values.

How?

Enter TypeScript's keyof and typeof operators.

Here's an example of how you can use these operators to extract types from both keys and values of an object:

const user = {
  name: 'John',
  age: 42
}

type UserKey = keyof typeof user; // "name" | "age"
type UserValue = typeof user[UserKey]; // string | number

In this example, we define an object user with two properties: name and age. We then use the keyof operator to extract the keys of the user object and assign it to the UserKey type. This results in a union type of "name" and "age". Next, we use the typeof user[UserKey] expression to access all possible values of the user object. This results in a union type of string and number.

Let's take a closer look at keyof and typeof operators:

keyof: This operator returns a union type of all the keys in an object. In the example above, we used keyof user to extract the keys from the user object.
typeof: This operator returns the type of a value. In the example above, we used typeof user[UserKey] to extract a union of the types of the values in user.

Using keyof and typeof operators, you can extract specific types from objects and build more robust and reliable TypeScript applications.

Hope this helps!

Using createGetInitialProps with NextJS Functional Components

2023-03-08T00:00:00+00:00

Mantine is a UI component library I love.

The Mantine docs show how to use Mantine in combination with NextJS. You have to use a createGetInitialProps function in the pages/_document.tsx, but their example uses a React class component.

No one likes class components.

So I'll show you how to do it with a functional component.

I assume you're somewhat familiar with NextJS and are trying to configure Mantine. The _document.tsx file is just a part of the NextJS file structure (more info in the NextJS docs)

Using createGetInitialProps with a functional component is pretty straightforward. All you have to do is define a getInitialProps function inside your component.

Here's an example of how your pages/_documents.tsx file could look like:

import { Html, Head, Main, NextScript } from "next/document";
import { createGetInitialProps } from "@mantine/next";

const getInitialProps = createGetInitialProps();

type Props = {
  initialProps: any;
};

function Document({ initialProps }: Props) {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Document.getInitialProps = getInitialProps;

export default Document;

As you can see, the function getInitialProps returned by createGetInitialProps() is attached to the Document as a static method.

And that's it! You now have a Document functional component with getInitialProps support.

I hope this helps!

Building the Flatten Type with Typescript: A Tutorial for Beginners

2023-01-01T00:00:00+00:00

Typescript learning can be challenging but rewarding. To improve your understanding and skills, you can try building types and analyzing them piece by piece.

In this post we'll build a Flatten type.

The Flatten type is a utility type that takes an array of arrays and flattens it into a single array. It can be used to simplify the process of working with nested arrays.

type Flattened = Flatten<[1, 2, [3, 4], [[[5]]]]>
// [1, 2, 3, 4, 5]

We have to somehow look inside the input array recursively, and spread any elements we find to be arrays.

Let's see how to do it step by step:

First, define the Flatten type as a generic type. It needs to take a type parameter which is the array we will provide when using the type.

type Flatten<T extends any[]> =
// implementation goes here

With T extends any[] we enforce the parameter T to be of type any[] .

Next, we're going to "look into" the array and get the values. We can do this with the infer keyword, which is used in the context of a conditional (extends keyword).

type Flatten<T extends any[]> = T extends [...infer S] ? S : [];

type Test = Flatten<[1, 2]> // this is just going to be [1, 2]

The spread operator (the 3 dots in ...infer S ) means that we are "grabbing" all values inside the array, not just one.

For the false branch let's simply return [], as it is the case of T being an empty array.

Now, we want to look at the values inside the input array one by one, and check if they are arrays or not, because if they are arrays we want to flatten them. To do this, we can split the contents of the array into two inferred types: First and Rest :

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First
  : [];

type Test = Flatten<[1, 2]>; /* this will now be 1, as the type is only
returning the first value in the array */

Here we used tuple destructuring.

Now let's check if the first element is an array. We need a conditional, which in typescript is done with extends .

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? // true branch, First is an array
    : // false branch, First is not an array
  : [];

In the true branch, First is an array, so we want to recursively call the Flatten type (we want to flatten it):

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? Flatten<First>
    : // false branch, First is not an array
  : [];

In the false branch, we could try to just use First without the need to flatten it. Let's try it:

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? Flatten<First>
    : First
  : [];

You might be noticing something. Right now, all this type is doing is returning only the First element of the array. What about the Rest of the array? We're never doing anything with it. When First is an array, it makes sense to spread the First along with the Rest like so:

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? Flatten<[...First, ...Rest]>
    : First
  : [];

What about when First is not an array? How to take into account the Rest

Can we do this?

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? Flatten<[...First, ...Rest]>
    : [First, ...Rest]
  : [];

No. It is obvious that [First, ...Rest] will result in the same input array. This is not enough. Rest is the same input array minus the First element, which has already been processed. Even if the First element is not an array, we need to recursively check the Rest of the array elements to check which ones are arrays.

How can we continue flattening the Rest of array elements?

Any idea comes to mind?

Yes, we can just use the type we're creating!

type Flatten<T extends any[]> = T extends [infer First, ...infer Rest]
  ? First extends unknown[]
    ? Flatten<[...First, ...Flatten<Rest>]>
    : [First, ...Flatten<Rest>]
  : [];

This might look slightly convoluted at this point, but Flatten<Rest> is taking the first element of the Rest array and flattening it. This is done recursively until Rest is an empty array or, what is the same, until all elements of the T array have been processed.

Now we can verify that the type works, for example, with:

type Flattened = Flatten<[1, 2, [3, 4], [[[5]]]]>
// [1, 2, 3, 4, 5]

I hope this tutorial has helped you understand how to build the Flatten type with typescript. Happy coding!

Easily Transfer Money from Toptal Pay to Your European Bank Account in 2023

2023-01-01T00:00:00+00:00

If you are based in Europe and working for Toptal, like me, you will probably want to transfer money from Toptal Pay to your European bank account. There are several ways to do this, but some options are more cost-effective than others.

Since I didn't want to lose half my money in fees before even being able to use it, I did some tests, research and asking around and found what seems to be the cheapest, fee-light way.

All you need is a Wise account and a Revolut account, which you should be able to get in a few days with just an internet connection.

Here's a step-by-step guide to help you make the most efficient and cost-effective transfer. It feels fairly convoluted at first glance but it's easy-peasy to do:

Sign up for a Wise account and create a US bank account. This will be the intermediary account for your transfer.
Sign up for a Revolut account. Revolut is great because it offers low currency exchange rates. You will most likely upgrade to the premium plan, which costs 8 Euro per month. You want to do this because the premium account offers lower currency exchange rates as long as you transfer more than $1000 per month. In practice, this means that if you make more than $1800 per month you're better off with the Premium account.
Transfer the money from your Toptal Pay account to your Wise US bank account. There is a flat fee of $0.5 for this transfer, and it will take 2-3 days to complete.
Transfer the USD from your Wise US bank account to your Revolut account. This transfer will also take 1-2 days to complete. Here, make sure to transfer USD to USD. Do not convert the currency to Euro, because the Wise exchange fees are higher.
Use your Revolut account to exchange your USD for EUR at the market rate plus a small fee.
Transfer the EUR from your Revolut account to your European bank account. The transfer should arrive immediately. You could also use Revolut as your main bank account, if you prefer that.
Enjoy your hard-earned funds! 💸

By following the steps above, you can transfer money from Toptal Pay to your European bank account efficiently and at a low cost.

I hope it was useful to you!

How to implement the Pick generic in Typescript

2022-10-29T00:00:00+00:00

The TypeScript utility Pick constructs a type from a set of properties from another type. For example:

type Book {
  title: string;
  author: string;
  price: number;
}

// Here we "pick" title and author, but not price
type TitleOrAuthor = Pick<Book, 'title' | 'author'>

const titleOrAuthor: TitleOrAuthor = {
  title: 'The Lord of The Rings',
  author: 'J.R.R. Tokien'
}

Note how the type TitleOrAuthor does not have a price property.

How would we implement the generic type Pick?

Let's see how, step by step.

First, we know from the definition that the generic will accept two types:

type MyPick<T, K>

Then, we need to look at each property and compare it to K. So we start by mapping (or "looping over") T

type MyPick<T, K> = {
  [Key in keyof T]: any
}

Here Key in keyof T can be read as "I am looking at each key of T, and I will assign it to Key". Kind of like a loop.

The type of each property is going to be unchanged, which means: it's going to simply be the property Key of the object T. Or T[Key]:

type MyPick<T, K> = {
  [Key in keyof T]: T[Key]
}

With that, we basically end up with the same type. In other words:

type MyPick<T, K> = {
  [Key in keyof T]: T[Key]
}

type TypeA = {
  foo: 'bar'
}

type TypeB = MyPick<TypeA, any>
// TypeA and TypeB are the same type

Let's add the cherry on the cake that will make it work.

We need a way to say: "if the current Key is one of those in K pick it, otherwise, ignore it". If... In other words, we are going to need a conditional type

Conditional types follow this syntax: condition ? true expression : false expression

In our case, the condition is Key extends K. If K is a union type, for example, 'title' | 'author', then, if Key is either 'title' or 'author' then the condition will be true.

For example:

'title' extends 'title' | 'author', this is true.

'age' extends 'title' | 'author', this is false.

Let's go to our type and plug this condition in there.

type MyPick<T, K> = {
  [Key in keyof T as Key extends K]: T[Key]
}

Notice the keyword as. This is necessary if we want to tell TypeScript that we want to do something with the Key. If we wanted to use the Key as it is, as key, we wouldn't need it. But in this case, we want to do something with it (compare it to K).

The above alone with not work though. We're missing the true and false expressions. Let's add them:

type MyPick<T, K> = {
  [Key in keyof T as Key extends K ? Key : ??? ]: T[Key]
}

For the true expression, it should be clear that we just want Key, because we want the same keys as the original object. But what for the false expression? What goes in there?

In the false expression, we want to tell TypeScript "since this Key is not one of K, just ignore it. Skip it!". TypeScript has a specific type for things that do not return any value. It is never. That's what we need there.

type MyPick<T, K> = {
  [Key in keyof T as Key extends K ? Key : never ]: T[Key]
}

It's similar to how functions with return type never, never reach the end of their execution.

Now we're done. If we used the type, it would work!

type TitleOrAuthor = MyPick<Book, 'title' | 'author'>

Web Accessibility Guidelines 2022 Update

2022-09-13T00:00:00+00:00

This is an extended version of my previous post, which was slightly outdated.

So you want to make your website accessible, or "a11y"? (accessible and a11y are the same thing).

Good for you!

Ideally, applying a11y guidelines should be a part of the development process, rather than an afterthought. I'm going to go over some steps you can follow to make your site a11y.

But first... If you are not familiar with the concept of accessibility, you should at least read a basic intro.

Okay, we're good? We're good. Let's continue.

Automatic testing

There are a handful of these types of tools. All of them run an audit check and provide a list of things to change. Some of these tools are described here in more detail: https://a11y.coffee/start-testing

WAVE Web Accessibility Evaluation Tool: in my opinion it is the tool that gives a quickest and most visual overview. I’d start here. It shows landmarks, a11y features, and a11y errors, among other things.
Additional tools that provide similar information:
- Firefox a11y audit in Firefox developer tools (also recommended)
  - In a11y dev tools tab, select: “All issues”, and “show tabbing order”. You can also simulate color deficiency.
- Axe Chrome extension
- Chrome's lighthouse audit in chrome developer tools
- Accessibility insights
- Axe cli. Yes! You can run a11y tests from the command line like so: axe luis-martinez.net/blog/a11y

My recommendation is to use the WAVE Web Accessibility Evaluation Tool to get a quick, visual idea of the a11y issues in the page, and then fix them.

Use an a11y checklist to discover issues that automated tools might have overlooked: https://www.a11yproject.com/checklist, https://webaim.org/standards/wcag/checklist or https://www.wuhcag.com/wcag-checklist/

Go through one of the checklists and make sure your website passes every item.

Manual testing

Lastly, cross-check the following use cases:

Interactive elements should follow ARIA guidelines. Explore the list of WAI ARIA patterns and make sure the ones you use in your page follow these guidelines
Add a "skip to content link", if suitable. Suggested read: https://webaim.org/techniques/skipnav
Navigate each page with the keyboard. Tab through the site and make sure every interactive element is focusable and has a distinct focus state. Suggested reads: https://web.dev/how-to-review/#start-with-the-keyboard, https://webaim.org/techniques/keyboard/
Each page should be screen reader navigable (see screen readers section)
If you are building custom widgets, make sure they are a11y (see Custom widgets section)
Touch points (interactive elements on mobile devices) should have appropriate dimensions on touch device sizes: at minimum 48x48 pt for touchable areas, and 32 pt of space in between touchable elements.
View the site in both grayscale and high contrast and make sure it is readable. I recommend the High Contrast chrome extension, which will enable you to select a handful of color modes. On Firefox, you can use the accessibility tab in the dev tools. Otherwise, google "website grayscale + your browser" and see what you find.
View the site at 200% magnification and make sure everything still works. For this, simply use the native zoom of the browser, usually ctrl/cmd and the + key.

About screen readers

A screen reader is a software that reads the content of the screen for users that, for example, are visually impaired. Become familiar with at least one screen reader.

Depending on the operative system, there are different screen readers available:

Windows users have NVDA
Mac uses have VoiceOver
Ubuntu users have Orca
For chrome, there is the Screen Reader extension, which is like a lite version of the above. If you use this extension, you can listen to the screen reader announce the interactive elements by tabbing. If you want the screen reader to read non focusable content, you will have to select it by clicking with your mouse.

If for some reason you can't use a screen reader, you still have the accessibility tree view: it is what screen readers read when navigating a site. You can see it in the Chrome dev tools, by clicking on the button with an icon of a person, in the Elements tab.

In Firefox, the a11y tree is displayed in the "accessibility" tab of the dev tools.

I won't go into how screen readers work. Get familiar with one of them, and use it to test your page for a11y.

To give you an idea, the screen reader reads:

The role or type of the element. For example, a link, an article...
The accessible name of the element. For a link, it would normally be its text content
The element's value, if there is any. For example, the current value in a text input
The element's state, if there is any. For example, the checked state in a checkbox

Things to keep in mind:

Screen reader users usually navigate a page using headings and landmarks, so review those. Use the h1-h6 hierarchy and landmarks correctly. Use accessible landmarks as a reference.
All images should have a descriptive alt text, which describes the image to someone who cannot see it. However, if they are only decorational, leave it empty: alt="".
All controls should have a label.
All custom controls should have a role and any required ARIA attributes.
As screen reader users navigate forms control to control, place any instructions inside the label of the associated control form.
The keyboard navigation order should make sense.
All visible content of the page should be accessible to screen readers (except anything that is only visually aesthetic).
Handle content depending on its required visibility:
- If content is hidden both from screen readers and visually, use display: none or visibility: hidden.
- If content is visually present, but hidden from screen readers, use aria-hidden="true" and possibly tabindex="-1", to prevent keyboard focus.
- If content is visually hidden, but accessible to screen readers, use css similar to this (copied from tailwind docs):

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Custom widgets

Semantic html (article, main, h1, input, button, etc. as opposed to div and span) has by and large built-in accessibility, so try to use native html as much as possible. However, if you're building a custom widget without semantic html, you might need to take care of accessibility entirely on your own. Research online how to make the widget a11y, according to the W3C specification and using the appropriate ARIA attributes.

Automated tools might not detect your custom widget, so you are entirely on your own.

Things that you will need to consider:

What role does the widget fulfill?
What states and properties does the widget need?

Finding a similar widget in WAI ARIA patterns and using it as reference might be a good start. Then follow the checklists and manual steps described in this post.

If you have a site built on just html and css, the library cypress-axe lets you run a11y checks in cypress tests. Take a look at this repo to play with it yourself: https://github.com/luismartinezs/axe-a11y-html

If you use a frontend library, such as React or Vue, you can incorporate a11y libraries in your development process. For example, for React you can run automated a11y tests in cypress, or identify a11y issues with Storybook. Check out this repo to see it all working together with React: https://github.com/luismartinezs/react-a11y-axe

What next?

There is much more to a11y than this post can encapsulate. You might start by reading about all html elements, to see what is actually possible in terms of native html. Then, take a look at all ARIA attributes as well as all ARIA roles.

Check also the list of resources at the bottom, in particular:

Read the recommended readings
Take the free Udacity course on accessibility

Resources

Other resources

https://www.w3.org/TR/wai-aria-practices/ Main resource for WAI-ARIA guidelines
https://webaim.org/techniques/skipnav Skip navigation link
https://webaim.org/techniques/css/invisiblecontent Invisible content for screen readers
https://css-tricks.com/accessible-svgs A11y for svg
https://www.w3.org/WAI/fundamentals/accessibility-principles W3C A11y principles
https://www.w3.org/WAI/standards-guidelines/aria WAI-ARIA overview
https://developer.mozilla.org/en-US/docs/Web/HTML/Element Reference for HTML elements
https://www.w3.org/WAI/tutorials/forms/labels Different ways to label form inputs
https://webaim.org/techniques/forms/controls A11y for form controls
https://www.w3.org/WAI/tutorials/forms/notifications A11y user feedback and notifications
https://webaim.org/techniques/keyboard Keyboard navigation
https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets Making custom widgets a11y
https://www.w3.org/TR/wai-aria/#roles List of WAI-ARIA roles
https://www.w3.org/TR/wai-aria/#states_and_properties List of WAI-ARIA states and properties
https://www.w3.org/WAI/ARIA/apg/patterns Authoring practices for widgets
https://a11yproject.com/posts/what-is-color-contrast What is color contrast?
https://inclusive-components.design In-depth building of accessible components
https://www.tpgi.com/the-browser-accessibility-tree/ About the web browser accessibility tree
https://www.adrianbolonio.com/blog/accessibility-with-storybook A11y and Storybook
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes List of all ARIA attributes
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles List of all ARIA roles
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions ARIA live regions

Tools and extensions

https://wave.webaim.org/ Wave a11y evaluation tool
https://developers.google.com/web/tools/lighthouse Chrome lighthouse
https://accessibilityinsights.io/ microsoft accessibility insights, can be also used to test a11y for desktop and mobile apps
Screen reader chrome extension (You can't "disable" it. Just remove it when you don't use it)
https://marketplace.visualstudio.com/items?itemName=deque-systems.vscode-axe-linter Axe VSCode extension
https://github.com/dequelabs/axe-core-npm/tree/develop/packages/cli Axe-cli
https://github.com/dequelabs/axe-core Axe-core library for continuous integration environment
https://github.com/component-driven/cypress-axe Axe library to use with Cypress testing library
https://github.com/dequelabs/axe-core-npm/blob/develop/packages/react/README.md Test a React app with axe-core
https://colorable.jxnblk.com Find colors that have enough contrast
https://github.com/jsx-eslint/eslint-plugin-jsx-a11y ESLint plugin to detect a11y issues in your code

Screen readers

NVDA (Windows)
JAWS (Windows)
VoiceOver (Mac)
Orca (Ubuntu)
Screen Reader extension for Chrome

Checklists

Courses

https://www.udacity.com/course/web-accessibility--ud891 (free)

How to use different firebase hosting environments with React and Vite

2022-08-04T00:00:00+00:00

Imagine you're building a React app with Vite and powered by Firebase, and you use Firebase hosting.

For local development you can emulate Firebase, but you can also have a LIVE Firebase project for development.

For this, you need to create a new Firebase project, you need to build the app locally using the correct environment variables, and lastly you deploy it.

This is how you make it work:

Create a new Firebase project for development from the Firebase Console. You might call it my-app-development, my-app-staging, or whatever you want.
Inside the Firebase project, create a new web app and take note of the config values.
In the local project in your computer, add the new Firebase project, running this in the root of the project: firebase use --add, select the new project you just created and give it any alias you want (dev or whatever)
Create a file named .env.[mode].local, where [mode] is the name of the new environment. For example: .env.development.local, you can read more about how Vite handles environment variables
Add the config values from the Firebase app (and any other env variables you need) to the new env file
Add a build script to your package.json file looking like this: "build-dev: "tsc && vite build --mode development". If your environment is named different than development (e.g. staging), then use it instead.
Run the build script you just created: pnpm build-dev
Deploy to Firebase: firebase deploy -P dev
- You could also have a deploy script: "fb:deploy-dev": "pnpm build-dev && firebase deploy -P dev"

If you use the firebase deploy command, remember to build your project locally first! I spent 2 hours once trying to understand with my LIVE project wouldn't update after a deploy.

Congratulations, you did it!

Fix import.meta.env Unexpected token error in Vite

2022-08-01T00:00:00+00:00

If you use Vite with environment variables which sometimes are undefined depending on the build and environment, you might be getting an error like this:

error during build:
Error: Unexpected token (Note that you need plugins to import files that are not JavaScript)

And the cause is an environment variable that is not defined.

The code that triggered such error in my case was:

const useEmulator = () => import.meta.env.VITE_FIREBASE_EMULATOR as string

To fix an error like this, change the above code into:

const useEmulator = (): boolean => {
  return import.meta.env.VITE_FIREBASE_EMULATOR !== undefined && import.meta.env.VITE_FIREBASE_EMULATOR === 'true';
};

Happy coding!

Fix: Cannot find module 'MyComponent.mdx' or its corresponding type declarations in React

2022-08-01T00:00:00+00:00

If you are trying to import .mdx files with Typescript in your React project, you might be getting an error looking like this:

Fix: Cannot find module 'MyComponent.mdx' or its corresponding type declarations in React

Here's how to fix it:

First, install @types/mdx:

pnpm i -D @types/mdx

Then, inside your project, add a types folder with a mdx.d.ts file (e.g. ./src/types/mdx.d.ts), and paste this in the file:

declare module '*.mdx' {
  let MDXComponent: (props: any) => JSX.Element;
  export default MDXComponent;
}

Now open your tsconfig.json file, and do these two things:

Add "mdx" inside "types":

{
"compilerOptions": {
    ...
    "types": ["react/next", "react-dom/next", "mdx"]
    },
  ...
}

Make sure the path of the mdx.d.ts file is included. If you added it inside the src folder, this should be enough:

{
  ...
  "include": ["src"],
  ...
}

It should work now. Good luck!

How to use VSCode to make Anki cards easily

2022-04-30T00:00:00+00:00

Why a new post about Anki?

For the past years I've used Anki to learn programming effectively.

Since I became a web developer, I've added a few tools to my arsenal. So I thought about leveraging them to ease (and improve!) the creation of Anki cards.

Can I create new cards and add them to my deck faster? Can I make the code in the cards look nicer? Can I create the cards with my favorite text editor, VSCode? Can I ...?

The answer is yes, yes and yes.

Let me show you what I found.

How will it work?

We're going to connect our favorite text editor (cough) VSCode (cough) to Anki, as we will use it to create new cards. Why? Because with VSCode we can:

Auto-format code
Use snippets to create cards more quickly
Use extensions that do some of the work for us

We will write our cards in a markdown file in VSCode, then we will run a command that adds the cards to our Anki deck. Simple, yet powerful.

Install the stuff you need

Install Anki desktop app (and setup an account)

First of all, if you didn't use Anki before, create an account here: https://Ankiweb.net

You will use the same credentials to login in the Anki desktop app, and in the mobile app if you use it. The mobile app is optional but recommended since it's much more comfortable to study Anki on the phone.

Next, install the Anki desktop app: Go here https://apps.Ankiweb.net and click on the download button, then install the app for your operative system.

In the Anki desktop app, install the addon AnkiConnect

The add-on AnkiConnect will automagically transfer Anki cards from VSCode to Anki.

Open the Anki app, and go to Tools > Add-ons.

Click on the Get Add-ons button, paste the code 2055492159 in the input and click ok. You should see AnkiConnect added to the list of add-ons

If the code is wrong for whatever reason, you can get it from here: https://Ankiweb.net/shared/info/2055492159, or googling for AnkiConnect.

Install VSCode

If you don't have VSCode installed, you will need to do so. Go here and do the thing https://code.visualstudio.com

Download my repo

I've created a repo with everything configured so that you can just go and create cards in a breeze.

Download it from here: https://github.com/luismartinezs/Anki

(click on the green "code" button)

If you use git, clone the project. If you don't (why not?), just download the zip file into your computer and unzip it. Then, open the project folder with VSCode.

When you open the project with VSCode, you might be prompted to install the recommended extensions. Accept it! If you don't receive that prompt, make sure you have the extensions that you need installed. The extensions needed are listed in .vscode > extensions.json

Create new cards

In the repo there is a README.md file with a detailed explanation, you can read it but I'll give you here the short version so you get into creating cards quickly.

Follow me here.

Open the file Anki.md.

Type a # followed by the name of the Anki deck where you want to add your cards, e.g. # My Dev Deck.

Add cards with no code

To add a card, add two empty lines, and in the second one just type anki.

You should see two options.

Choose anki-new-card to add a card with no code.

The cursor will automatically position itself in the "front" so just write down the front part of the card (e.g. What is the programming language of the web?).

If you hit the tab key, the cursor will move to the "back". Write it down (e.g. JavaScript).

Then the tab key again will highlight the tag. Fill it up (e.g. js)

You can add multiple tags like so: [#tag-1]() [#tag-2](). Mind the # symbol before the tag.

Leave a space in between tags! Otherwise, you'll get one single ugly-looking tag like tag-1()[#tag-2]()...

Add cards with code blocks

If you want to have code in your card, add two more empty lines, type anki and select anki-new-card-wth-code.

You will see this:

The triple ` marks the start and end of a code block. In Anki, this will be replaced by a block of code. Syntax highlighting --fancy colors that make the code readable, also works!

Type the short label for the language, e.g. html, css, js, ts, etc. That will act as a tag too.

Hit tab to highlight the front, then the back. You got it. Or feel free to edit the text normally.

After creating your cards with and without code, you could end up with something like this, for example:

Obviously, it is possible to have a code block only in the front or only in the back.

Auto-format the cards

Go to View > Command Palette... and type "format", then select Format Document. Or use the shortcut Ctrl+Shift+I (Linux, Windows). That should minimize the length of each line so that it fits the card on mobile.

Leave an empty line in between each part of the card, so that auto-formatting doesn't think they belong to the same paragraph and wrap them together.

Add the new cards to your Anki deck

Almost done! You have your Anki.md file with the cards you want to add to your deck. In the first line, after the #, you wrote the name of your deck (if it doesn't exist, Anki will create it).

Open the Anki desktop app, if it isn't open already.

Go back to VSCode and open the command palette (ctrl+shift+P), or View > Command Palette...

Then, type Anki, and select Send to own Deck. The new cards should show up in your deck, and the code blocks should look nicely!

If you get an error like this: connect ECONNREFUSED 127.0.0.1:8765, try to restart the Anki app

Happy studying!

References

Read the README.md file in my repo https://github.com/luismartinezs/anki
Read the documentation of the Anki VSCode extension https://github.com/jasonwilliams/Anki

Web Accessibility Guidelines

2022-02-20T00:00:00+00:00

Make sure to check my blogpost Web Accessibility Guidelines 2022 Update

Ideally, applying a11y (accessibility) guidelines should be a part of the development process, rather than an afterthought.

I propose the following steps:

1/ Automatic testing

There are a handful of these types of tools. All of them run an audit check and provide a list of things to change. These tools are described here in more detail: https://a11y.coffee/start-testing

WAVE Web Accessibility Evaluation Tool: in my opinion it is the tool that gives a quickest and most visual overview. I’d start here. https://wave.webaim.org/
Additional tools that provide similar information:
- Firefox a11y audit in Firefox developer tools (recommended)
  - In a11y dev tools tab, select: “All issues”, “show tabbing order”, and color deficiency simulations
- Chrome's lighthouse audit in chrome developer tools
- Axe browser extension https://www.deque.com/axe/
- Accessibility insights

In my opinion, running one of the above should be enough to cover this point.

2/ A11y checklist

Use an a11y checklist to discover issues that automated tools might have overlooked: https://www.a11yproject.com/checklist or https://webaim.org/standards/wcag/checklist

3/ Manual testing

Cross-check the following use cases:

Interactive elements should follow ARIA guidelines: https://www.w3.org/TR/wai-aria-practices/
Each page should be keyboard navigable
Each page should be screen reader navigable (navigate with closed eyes using keyboard and a screen reader)
Focus styles should be apparent
Touch points should have appropriate dimensions on touch device sizes: 48x48pt minimum for touchable areas, and 32pt of space in between touchable elements
View site in grayscale, make sure it is readable (use nocoffee from the resources section)
View site in high contrast mode, make sure it is readable (use nocoffee from the resources section)
View site at 200% magnification

Resources

General resources

https://www.w3.org/TR/wai-aria-practices/ Main resource for WAI-ARIA guidelines
https://a11y.coffee Quick intro to the concept of a11y
https://webaim.org/techniques/skipnav Skip navigation link
https://webaim.org/techniques/css/invisiblecontent Invisible content for screen readers
https://css-tricks.com/accessible-svgs A11y for svg

Tools and extensions

https://wave.webaim.org/
Chrome lighthouse
AXE
Microsoft accessibility insights, can be also used to test a11y for desktop and mobile apps
https://accessgarage.wordpress.com/2013/02/09/458/ (download chrome extension nocoffee and use it to simulate different levels of visual impairment)
https://chrome.google.com/webstore/detail/screen-reader/kgejglhpjiefppelpmljglcjbhoiplfn Screen reader chrome extension (annoying, will force you to reinstall / uninstall each time to keep your sanity)
https://marketplace.visualstudio.com/items?itemName=MaxvanderSchee.web-accessibility VSCode extension

Checklists

Courses

https://www.udacity.com/course/web-accessibility--ud891

The NoCoffee extension for Chrome seems gone. For high contrast mode, you can use this High Contrast extension for Chrome

15 lessons I learned from playing Starcraft 2

2021-09-05T00:00:00+00:00

I love Starcraft since 1999.

Starcraft is a real-time strategy game where you build an economy and an army to beat your opponent.

During play, you juggle your focus between developing your economy (known as "macro") and micro-managing your army (known as "micro"). And it's not easy.

Learning to play Starcraft means learning a very complex skill. So complex, that it feels almost impossible to do well as a beginner.

Web development is also a very complex skill. Lots of moving pieces.

So, as a fan of Starcraft, I (naturally) thought:

How can I generalize the complex process of learning to play Starcraft to other skills?

In what is perhaps a fun thought experiment more than anything, I came up with the following.

Before that, a few disclaimers:

When I write Starcraft I'm actually referring to Stracraft 2. I didn't play the first game for ages. But for the purposes of this article, it doesn't make any difference.
By writing this I don't mean to suggest I'm any good at playing this game. I'm atrocious at it. But I thought some concepts of the game are interesting enough to write about.

Grab your nachos and enjoy.

1. You don't learn to play the game, you learn a specific way to play the game

In Starcraft there are 3 races you can play, and each has its own strategies.

Commonly, you don't learn to execute all possible strategies for all 3 races flawlessly. Instead, you pick one race. Then, you get very good at a specific way to play it.

Likewise, a developer doesn't try to learn all technologies, all web stacks, how to make all types of websites and applications... Devs learn a specific set of technologies, learn to develop a specific type of applications in a specific way and with a specific structure.

If there's a need to change and adapt, it's always possible.

The goal of the game is not to learn everything. It is to win more over time.

Likewise, the goal of learning development is not to know everything, it is to produce high quality work efficiently.

That doesn't mean one should reject aquiring a broad knowledge. It means that one shouldn't try to excel with all tech stacks.

2. Redefine "winning" into something that benefits you

Typically, the goal of any individual game is to defeat the opponent. Turns out, focusing on winning is not useful to learn to play. That won't help you improve, except by coincidence. You won't know where to focus your energy.

Even worse.

If your goal is winning at something and you fail, you might feel frustrated and stop.

Having the goal to win the game is the same as having the goal to play very well. Too generic and overwhelming. Where to focus? What to do next?

Winning or losing one game is irrelevant. Increasing your number of wins over time is what matters.

Any one individual loss doesn't matter as long as you don't define success that way.

So don't do that.

Instead, ask: What is the next thing you need / want to improve on?

Then, redefine a win as having practiced that one thing with focus, ignoring the rest. That is your success, because by doing this, you will get better at that one thing. And by getting better at that one thing, you'll win more in the long run.

3. Learning something complex is within your grasp, if you take it one bit at a time

Faced with a huge task like learning to play Starcraft, or learning web development, might be so daunting that it feels impossible. As if you were in front of an insurmountable mountain.

It isn't.

Understand that no matter how complex a skill might look, it is within your grasp to learn it, if you commit, persevere and are patient.

Do not try to learn everything at once. Focus on one tiny aspect of the skill and allow yourself to completely suck at everything except at that thing.

Practice that one tiny thing many, many times, until you develop muscle memory (the ability to do that well without even thinking about it). As that happens, you'll be able to do the thing without speding mental energy on it, so you'll be able to focus on the next thing.

4. Review your mistakes to figure out what you need to improve, but be gentle with yourself

When things go wrong, when you lose, look back. No matter how much you want to blame the universe, almost always there's something you could have done to prevent losing.

So be critical of yourself and don't shy away from your mistakes. Look as closely as you can into them, to figure out what went wrong.

What went wrong? Why? What did you do well despite losing?

Learn what you can from it. Figure out what is causing your losses, and use that knowledge to decide what you need to improve next.

But equally importantly, never beat yourself up for your mistakes. Be gentle with yourself. Mistakes are unavoidable, we're all human. Mistakes are part of the game.

Always remember that learning from a loss is more important than a win.

5. Start by fixing the first thing you did wrong

Also known as The Principle of the First Cause (I probably made up that name).

When something goes wrong, we have a tendency to blame whatever happened immediately before the disaster.

Don't do that.

Right before a loss, things were probably too messed up already due to lots of mistakes being piled up. It's likely that at that moment there's nothing you could have done anymore to prevent your loss.

Thus, blaming the last thing that happened can be not only pointless, but can also hide the true cause of the loss.

So look again, look better, look further back.

Find the first thing you did wrong that led to the failure, and fix that.

When you fuck up, ask yourself: What started this mess?

6. Good habits are king, don't let anything interfere with them

Starcraft tells you that good habits are king, and without them you're hopelessly doomed.

To understand why, let's take a look at the concepts of macro and micro.

In Starcraft, players split their attention between macro and micro tasks.

Macro = grow your economy and spend your resources
Micro = control and manage your army units in the battlefield

Macro is equivalent to important tasks performed over and over whose effect compounds and in the long run mark all the difference. Think of them as good habits, like exercising, investing and healthy eating. Neglecting them will have a disastrous result over time and during your entire life.

Micro is equivalent to tasks that have an immediate positive effect, but almost always have very little impact in the long run. Think of these as the little random things that creep up in daily life.

Starcraft teaches you that neglecting macro to spend more time in micro is almost always a bad idea, and should be avoided. I think this is true in real life too.

Don't let the micro of life distract you from staying on top of your macro.

Give your important habits priority over the chaotic and random events of life.

7. Establish habits designed to move you forward in life

To be on top of their macro, players perform a series of tasks or rotations routinely every few seconds. These rotations are known as a macro cycles. This is essential for a good game.

Success in life too needs habit rotations that performed routinely move you forward and lead to good outcomes.

How you define success in life is entirely up to you of course.

The macro cycles of your life would be a set of habits you do repeatedly and that you have purposefully chosen based on your definition of success.

For example, a very basic habit rotation would be:

Exercise every 3 days
Fast once a week
Read 1 hour per day

Don't go aimless on your day to day without knowing what to do. On the contrary, mindfully pick a habit rotation and prioritize doing it, because its compound effect will have a profound impact over time.

8. Get rid of bad habits

In Starcraft, F2 selects your entire army. It's very tempting for beginners to do that because it's easy. However, it is a bad habit that will get on the way of improving and will have to be unlearned.

Find the things you do often that get on your way. Things that are a waste of time and energy. It's very tempting to be lazy and to keep on doing things the bad way just because you started doing them that way (maybe you didn't know better).

Are you repeating a manual task over and over? Don't be lazy, automate it.

Do you mindlessly watch YouTube or play too many video games, and that leads to excessive distraction? Stop.

Kill or minimize your bad habits.

(That time when Starcraft teaches you to stop playing Starcraft, cough...)

9. Put your habits (or your decision about them) on auto-pilot

Once you've decided:

What habits you'll do
How often you will do each
That you will give them priority

There's really no decision-making left about that, and it should make things easier. You don't have to think whether you do them or not. And it doesn't matter what else you think you have to do, or whether you're busy with something else.

Simply do them.

You will have more decision-power to spend on other things.

I suggest that for each habit you set some kind of timer, so that you can keep track of when you have to do them without having to think.

The multitimer android app works for me.

10. To improve quickly, practice often

Practice smart, not hard. Sure. But practice.

And practice often.

Starcraft pro-gamers practice 8 to 12 hours a day. There's probably no need to reach this number of hours when learning programming.

But the simple truth is that lots of cumulative practice will bring you where you want to be faster. You get good at what you do often. The more you practice, the better you'll get.

And frequent practice will help.

Practicing one skill daily, or even multiple times a day, will skyrocket the speed at which you learn. Don't let lots of time go between practice sessions.

And of course, simply thinking that you want to be a good developer without follow up action won't bring you anywhere. Make sure you're not doing that.

Massive results require massive action.

11. Accept that you will suck at first

When you start practicing a new skill, or anything new that you've never done before and are not familiar with, you will feel unconfortable. This will happen particularly when learning a complex skill composed of many sub-skills, like Starcraft or programming.

You'll feel deep inside that you suck. That you're hopeless. It will feel like going uphill when you only want to slide down into comfort.

Allow yourself to suck. Allow yourself to suck badly, and accept that it is perfectly fine for you to suck now. Because eventually you won't.

Simply push through that phase.

12. Accept that losing is part of the game, concede when you can't win

Accept defeat as a natural part of life. Try to win, try to face the odds looking for that chance of victory, even if it's small. Struggle in front of challenges.

But sometimes there's a point when defeat is inevitable, regardless of what you do from that point onwards. In that case, any more energy spent in that one battle is a waste.

When you realize you can't win, accept defeat. Give up. Learn from what caused your defeat. And move on to the next chance of winning.

A simple but hard piece advice.

13. Practice when sharp, rest when tired

Without a fresh or rested mind, you can't perform well. Working to exhaustion, burning the midnight oil, can be damaging to the quality of your work.

Do mentally demanding tasks only when your mind is sharp. If you are tired, it's much better to take a rest, sleep, take a walk... switch off your brain for a while.

14. Tweak your lifestlye, don't settle for unoptimal

Starcraft comes out of the box with default settings. These are ineffective and can lead to bad habits. So players tweak them to be able to play more effectively.

They generally copy the settings of a pro-gamer and go from there. Later customizing it more to their playstyle, once they understand better how the game works.

Society too seems to be configured out of the box with some defaults. In general terms: go to school, go to university, get a job, and work for 40 years while you pay taxes. Whereas this doesn't need to be terrible, let's not overestimate how good it can be, and realize that you don't need to follow all these things for your life to be good.

Look for pros: people who are in a situation that you desire. This could be a successful freelancer, a strong athlete, a charismatic and brave person, someone you admire.

Copy their habits and mindset, learn from what they do as a first approach. That will probably put you in a better path than before.

Then don't get forever stuck in doing what they do. Start doing things your way.

15. Your skill at doing something is really your skill at doing it in less than ideal circumstances

The controlled environment where you train and practice your skills and real life are two different things. Real life is unpredictable and wild. Sometimes shit hits the fan, the storm hits.

How to confront that?

Level up your skill, not to the bare minimum, not to deal with hypotheticals where everything goes according to plan, but to the level where you can deal with messy real-life scenarios.

Over-practice. Over-prepare. Be able to perform on the theoretical scenarios blind-folded.

Then, when shit hits the fan don't freak out, don't feel like a failure, because that's normal. Do your best, then pick up the pieces after the storm.

Don't expect your successes to be elegant, expect them to be messy.

Using default function parameters wrong and right in JavaScript

2021-06-03T00:00:00+00:00

This is a short story of two JavaScript functions.

What they do is not important. I want to illustrate something about default function parameters.

First, I had a function getColorOnBackground, which took the parameters backgroundColor and, optionally, dark and light. It returned either dark or light:

function getColorOnBackground (
  backgroundColor,
  dark = 'text-gray-900',
  light = 'text-white'
  // `dark` and `light` are CSS classes
  ) {
  // Do some logic
  // Return either the `dark` or `light` values
}

It needed to set default parameters for dark and light, otherwise, they couldn't be optional.

The other function is getTitleColorFromData, and it calls the first one, getColorOnBackground.

function getTitleColorFromData (data) {
  if (data.backgroundColor) {
    // here call the other function
    return getColorOnBackground(data.backgroundColor)
  }
  // do other things
}

This function has at least one limitation, the option to use custom values for light and dark is lost. So, naively, what we want is:

function getTitleColorFromData (data, dark, light) {
  if (data.backgroundColor) {
    // here call the other function
    return getColorOnBackground(data.backgroundColor, dark, light)
  }
  // do other things
}

This will work.

However, as the function does more things, I expect that the number of arguments might increase. When this happens, I like to turn the optional arguments into an object.

This was my (dumb) try:

function getTitleColorFromData (data, { dark = null, light = null }) {
  if (data.backgroundColor) {
    // here call the other function
    return getColorOnBackground(data.backgroundColor, dark, light)
  }
  // do other things
}

I replaced dark, light by { dark = null, light = null }.

Here I was thinking: "if I don't pass light or dark values, just use the fallback set in the getColorOnBackground function". Setting the default values to null was a naive attempt to make them be falsy and thus fallback to the default parameters.

That was very wrong.

Default parameters - JavaScript | MDN says:

If default parameters exist, e.g. function myFunction (value = 'default') {...} they will only be used in two cases:

If no value is passed when we call the function

If a value is passed and is explicitly set to undefined

null is not the same as undefined, so default parameters are NOT used if the passed value is null!

So, in my (dumb) attempt above, the nested function getColorOnBackground would always return null. :(

How to fix it?

An obvious solution would be to set the default parameters to undefined explicitly:

function getTitleColorFromData (data, { dark = undefined, light = undefined }) {
  if (data.backgroundColor) {
    // here call the other function
    return getColorOnBackground(data.backgroundColor, dark, light)
  }
  // do other things
}

That's not a good solution though. It carries one problem: I'm forced to always pass a second argument, like so: getTitleColorFromData(myData, {}).

Otherwise I get an error:

Cannot destructure property 'dark' of 'undefined' as it is undefined.

Plus, it's also verbose.

Fortunately, there's a good solution to this small conundrum:

function getTitleColorFromData (data, { dark, light } = {}) {
  if (data.backgroundColor) {
    // here call the other function
    return getColorOnBackground(data.backgroundColor, dark, light)
  }
  // do other things
}

The { dark, light } = {} means: "Use an empty object as a default parameter if no argument is provided". With this, light and dark will automatically be undefined.

Not only that works, but is also more flexible:

The second argument is totally optional. This will work: getTitleColorFromData(myData)
We can set the value of both parameters. This will also work: getTitleColorFromData(myData, { dark: 'text-gray-900', light: 'text-gray-100' })
We can set a value for one of the parameters: getTitleColorFromData(myData, { light: 'text-gray-100' })

Isn't the power of default function parameters wonderful?

How I use Anki to study programming: Anki setup and card creation

2020-08-07T00:00:00+00:00

Anki is a software to use flashcards (question and answer cards) on the computer or mobile. I use it to review what I learn when I am studying programming. Anki is an extremely valuable tool to prevent forgetting what I have studied in the past.

Thanks to using Anki daily for a long time, I can recall many concepts of javascript and other technologies even if I don't use them in my daily work, and even if I have never used them.

Anki reviews are a great way to avoid feeling lost among so many new things to remember while studying programming.

Anki is particularly useful to effectively digest the fundamentals of programming, when one gets started on this field.

I will explain how I setup Anki and how I create cards.

If you don't know what Anki is, you can get an overview here.

Download Anki

Head to AnkiWeb and download the software.

Most likely, you will want to create the cards in your computer and study them in your mobile.

So, download and install both the desktop version and the mobile app for whatever operative systems you use. Once you have installed the app, create an account. That will allow you to synchronize your cards and decks across devices.

Once you have an account, you'll do some initial setup.

Initial setup

We're going to setup Anki for the first time. You only need to do this once.

Anki initial setup

Create a new deck

You will be adding cards to something called a "deck". The first time you open Anki, you won't have any deck, so you'll have to create one.

Simply click on Create deck, and give it a name. Done. Easy, right?

Customize deck options

Optional, but highly recommended.

The default Anki settings might be "optimal" to memorize things, but have two fairly big disadvantages, in my opinion:

The review rate for cards is high. This means that you review a given card quite often.
The number of reviews per session is high. In a given (daily) session you will be reviewing lots of cards.

This makes the daily review session quite long. In between 20 and 40 minutes, or more. Honestly, I'm too lazy to spend that much time reviewing cards.

So, I tweaked the settings so that review sessions are shorter. About 10 to 20 minutes long.

To customize the deck options:

Click on the small gear icon next to the deck
Select Options
At the top, next to options group, click on Manage and then Add
Name the new options group whatever you like ("quick review", for example)
Use the following options:

These settings will give you effective review sessions which are not too long.

Create the cards

Your setup is ready. But your deck has no cards. Kinda useless.

But we're going to fix that.

If you know that you can import decks created by other people, you may be thinking: I'll import someone else's deck.

You could indeed do that, but I discourage it. Creating your own cards will help you study and force you to summarize what you are learning. And the cards will "make more sense" to you.

In short: create your own cards.

I concede that creating the cards can be a bit tedious sometimes, but it pays off. Consider it part of studying.

You can create cards in the app itself, using the add button. However, this is not how I do it most of the time, I prefer another method that for me is faster and more practical.

Let's jump into it.

How do I add cards to Anki easily?

Create Anki cards easily

Let's imagine you're studying array methods from the website javascript.info, and you see the following piece of information.

- arr.push(...items) – adds items to the end of an array

And you want to create an Anki card to remember this arr.push() method (don't worry if you have no idea what this is, it's just an example).

Now, open a text editor. Any will do. I use Sublime. You can use the same, or textedit, or notepad or whatever.

In the editor, you will write something like this:

Method that adds items to the end of an array"arr.push(...items)"js

Now you will say: What on earth is this, Luis!?

This will be the content of one Anki card. There are 3 fields, the front of the card, the back of the card, and the tags. In that order.

Front: Method that adds items to the end of an array
Back: arr.push(...items)
Tags: js

To indicate where the front ends and where the back starts, you need a separator, which could be any character. I use one double quote. I could use something else, but a double quote works just fine for me in 99% of the cases.

So, while you study, you will keep on adding cards in that same format, based on the things that you want to remember.

You might end up with something like this (you could have many more lines, the number doesn't matter):

Method that adds items to the end of an array"arr.push(...items)"js

Method that extracts an item from the end"arr.pop()"js

const element = _____Hello, world!_____ // Component renders a h1 heading"const element = <h1>Hello, world!</h1>"react

<a _____>Website</a> // Links to https://example.com"<a href="https://example.com">Website</a>"html

Note: You do NOT need to add these cards to your Anki deck! This is just a random example!

I want to point out three things here, that you may notice if you look at the previous example:

A new line, or line break indicates a new card
I use empty gaps like _____ very often in the front of the card. It's a simple way to indicate that there's something there that I am supposed to remember.
If you look at the last "card" (line), there's something wrong in there. As I mentioned we're using the double quote " as a field separator. However, in the last card, the answer itself contains double quotes. If we try to add that card like that, Anki will get confused and won't be able to tell what are the front, back and tags. We cannot use the separator character inside the fields themselves. The correct version of the last card would look like the following:

<a _____>Website</a> // Links to https://example.com"<a href='https://example.com'>Website</a>"html

Notice that I replaced the double quotes inside the back field by single quotes.

Import the cards in the text file to Anki

How to import cards to Anki

To add these as cards to Anki, we need to import the text file we have created.

Go to the Anki app, click on file, then import.... Then select the text file.

You will see something like this:

You will have to select the right deck where to import the cards. As for the card type, you should choose Basic.

Click on Fields separated by: Space, and here write a double quote. You probably figured out that this should be the separator we used in the text file.

If you didn't use a double quote as separator, then enter whatever you used.

When you click ok, Anki will automatically identify the 3 fields.

Once you click on Import, you are done.

Congratulations! You've just added cards to the deck and you can begin studying.

Using Anki to learn programming is no secret. I got inspiration from others that were doing it long before me. Derek Sivers and Jack Kinsella are two examples.

I used to review the cards while stretching my legs by taking a walk around my neighborhood.

If you skip a day it is not a big deal, but try to review your deck daily. You should notice positive effects almost immediately. After a few weeks of study in combination with daily Anki you will be surprised of how much you're capable of recalling.

You will almost feel like you had a superpower.

As they say in Japan, Ganbatte! (do your best)

Is higher education (e.g. a PhD) necessary to get a job as a junior developer?

2020-04-12T00:00:00+00:00

tl,dr: No. You need commitment and technical skills. Though a PhD helps your resume stand out, upping your chances to get interviews.

Why do I write this?

In October 2019 I submitted a post on reddit that got some attention (also in this blog. I also have a PhD in computational chemistry. A handful of commenters assumed that my PhD got me the job. I am thankful to them for making me aware of that point of view (I wasn't). I think it is a reasonable assumption. I also think it's mistaken, and I will now give my view on this point.

Keep in mind that the context is specifically getting a first job as a junior frontend developer.

My conclusions are quite obvious. Don't expect to find any "magic knowledge".

Did a PhD give me the job? In what way did a PhD help me?

No, it did not give me the job. I know because I asked the person who interviewed me.

A PhD helped my resume stand out in a positive way. It suggests intelligence, and the ability to work persistently in a complicated problem. Both are valuable to employers and make you look like a shiny pokemon. That made it easier to get an interview. However, once in the interview, what mattered was no longer the PhD, but my attitude and my technical skills. Imagining that my PhD gave me the job would be mistaken.

I hope it's obvious that a PhD will not miraculously help you nail the interview. So a more relevant question is...

Do you need a PhD or higher education to GET an interview?

You may say: "Without the PhD you would have never got an interview". I don't think it's true. We're hiring junior devs right now (February 2020). None of the candidates has a PhD. Half of them got an interview.

So, no (duh).

If a company filtered only resumes with PhD levels of education, they would run out of candidates very quickly. A PhD is rare and gets attention from employers, 100 billion %. It may give you an interview, but you don't need one to get an interview. And even if you get the interview, a PhD will not guarantee you the job if e.g. you lack technical skills. After all, 3 companies rejected me during my job hunting. I believe the reason is that I was too unskilled.

In sum:

A PhD is neither a requirement nor a guarantee to get a job.
To increase your chances to get an interview you should put something in your resume that makes it stand out in a unique and positive way.

What do you need to put in your resume to get an interview?

Give employers what they want.

In my opinion and experience, that is commitment and fundamental technical knowledge. Show that in your resume.

Commitment: show that you are motivated and committed to this career path.

Mention in your resume that you want to become a senior developer (take a look at the resume I used back then to see an example).
If you've done something in the past that required effort for a prolonged time, that shows that you are persistent and able to commit. Mention it. Examples are having worked for the same company for more than 18 months, a big personal project that took months to complete, an entrepreneurial activity, winning a prize in a competition...
If you decided to pay for one insultingly expensive bootcamp (which is unnecessary), make sure the employer can find their website so that they are able to check the price of admission. Your willingness to cash out suggests commitment.

Fundamental technical knowledge:

Add that you know HTML5, CSS3, JavaScript and React (as a frontend dev --- and yes, another framework will do). I go into a bit more detail on what technical skills are needed in my previous post (look for "the minimum to get a first job"). Don't bother lying about these, you wouldn't pass the interview anyway.
You can add MongoDB and NodeJS/ExpressJS if it is true that you know how to use them (every bootcamp seems to include these), but they are not necessary because as a junior frontend developer you wouldn't be doing anything with the backend and databases anyway.

Combine both things!

Show both commitment and knowledge at the same time.

If you learned by yourself, autonomously and using free resources (like I did) AND you have a solid foundation of HTML5, CSS3, JavaScript ES6 and React (or Vue, or Angular), that makes you an excellent candidate for a junior position. Automatically, you prove that you are committed and motivated, because otherwise you wouldn't have found the energy to push yourself through many hours of intense studying. Plus, you show that you will continue learning on your own, which is the icing on the cake in this ever-evolving field. In other words, it makes you exceptionally valuable.

Even if you feel that you lack in formal education, don't let it be a deterrent to pursue a career in development. The world needs you!

Useful links:

From jobless to junior developer in 5 months

2020-02-22T00:00:00+00:00

Tl,dr

From jobless and with no specific frontend knowledge to an entry level job in 5 months
Money spent: 0
Time spent studying: roughly 2.5 months, around 5 hours per day.
Study material: mainly freecodecamp modules 1 to 3 and javascript.info
Focused studying, with emphasis on deep understanding
Use a review system for the things you learn, Anki cards or something else
Put some effort in structuring well your resume so that it's relevant and easy to read

Introduction

I am going to explain how I transitioned from unemployed living in Barcelona and with barely any front end knowledge to employed in Amsterdam as an entry level front end developer, within 5 months. The main reason why I am writing this post is because, while learning, I met other front end students and many of them saw things unnecessarily hard.

I will explain what I did.

I hope this is useful to you.

Why studying programming?

I think it is important to start with a positive mindset that somehow you can do this and it is a good idea. I didn't decide to learn front end development right off the bat, I did it because I clearly saw lots of opportunities:

Using LinkedIn, I compared the amount of job offers (demand) with the amount of people with developer skills (offer). A simple LinkedIn search will give you some rough numbers. Programming had by far the best ratio of demand VS offer, compared to other markets I explored. In my eyes, programming became an obvious choice very, very quickly.

In the current market, as a developer odds are in your favor.

I talked to a few HR firms, and they all told me that becoming a developer is a great idea because there is a lot of demand, and therefore I would find a job in no time.
It's just common sense. Most companies, large or small, need some kind of web presence. Web technologies are constantly evolving. This means that you have endless opportunities to find new work.

This makes clear that web developer skills are currently very valuable, and that could help you find the idea of learning web development exciting.

Disclaimer:

I have no computer science degree, but I am more computer versed than the average person. During my PhD (in scientific research) I used linux all the time and became well acquainted with the unix shell (the command console) and the bare basics of programming languages. That was certainly useful to lose the fear to commands and consoles, but it is nothing you cannot acquire in a few days of studying.

Note: I've been told recently that having a PhD helped catch the eye of the interviewer.

Why front end web development?

I did compare offer VS demand ratios but it was not very obvious which field of engineering was a better choice. Other fields could have been an equally good or even better choice: data analysis, backend engineering or dev ops to name some. So I talked to people in the sector, asking them what field would bring me a job the fastest, and a couple of them recommended me to look into front end.

Literally one person told me: "learn HTML, CSS, JavaScript and React, and you're good to get a starting job".

He was not wrong.

Dev ops salaries are actually higher than in other fields. I would say ultimately depends on your own preferences and previous knowledge. For example, I picked front end for another reason, I am attracted to creating artwork and "visual works", so it was a more obvious choice for me. But that doesn't mean it's the best pick for everyone.

How did I study? What resources did I use?

FreeCodeCamp

I spent most of my waking hours studying in my room, since I was jobless anyway. I picked FreeCodeCamp, which I had seen recommended online, and followed its program for the first 3 modules. It is an entirely free (with optional donations if you want to help support it), very complete, "study at your own pace" introductory course.

I simply followed the program in FreeCodeCamp. It took me around one month to study the first three modules, which include HTML5, CSS3, JavaScript ES6, React/Redux, and a tiny bit of jQuery, Bootstrap and Sass. It is an excellent introduction to front end. You are going to be using most of these every day in your coding life.

Anki for reviews

One important thing I did right from the start was to take notes of what I studied to later convert them into Anki cards. Initially I also wrote summaries you can see them here, but I don't think these are worth the time spent on them. The Anki cards however were incredibly valuable. I created the Anki cards at the same time I studied, then every single day I studied the Anki deck. The main reason why Anki cards were so useful is that as you progress through the lessons, information keeps on piling up, and there's gonna be A LOT of new information you will have to learn. Without a review method, I would have forgotten most of the things I studied. Anki allowed me to remember almost everything in a very time-effective way.

I did not use Anki's default configuration. That would be worth its own article, but for starters you could read about the Janki method. Making Anki cards is an art, and it is possible to make it wrong. There are 3 main things to keep in mind:

One card = one and only one item to remember
Find a quick way to create the cards (Now I write the questions and answers in a plain text file and import the file)
Lower the repetition thresholds so that cards show up less frequently (to reduce the time spent in reviewing the cards)

That's all I did for about 4 or 5 weeks. I would say I spent on average 4 or 5 hours studying every single day, and it was hard work. If I had been working at the same time in a 40 hour/week job, I would have gone much slower. It is NOT EASY. It required full focus for hours, every day during weeks.

Anyway. I completed the first 3 modules of FreeCodeCamp. There are 7 modules in total, but I don't believe the last 4 are essential to find a job. They would be nice to have though, and would definitely increase your odds. But part of the reason why I am writing this, is to tell you what is the minimum you should do.

JavaScript.info

After completing the freecodecamp modules I decided I should become a "JavaScript expert", so I began reading javascript.info. This is a very in-depth journey into JavaScript, and of course, it is 100% free. I found this resource very useful, and took the same approach of studying while making Anki cards. Why did I want to learn more about JavaScript? I felt that learning one programming language very well was the best use of my time. Tools, frameworks, these come and go, but JavaScript has come to stay. At least for quite a long while. Having a good grasp of JavaScript is a great use of your time, and when job interviews come, they will test your knowledge about the language. Understand well its nuances: the keyword "this", the differences between arrow functions and function declarations, asynchronous code and promises, spread operators, destructuring assignments... sometimes it's gonna be a bit hard for you to tell what is important or what is not when it comes to JavaScript. Particularly in the beginning. In case of doubt, learn it. It won't hurt you.

What else did I do besides studying?

Besides studying frontend technologies, I also talked to people who worked as front end developers, recruiters, and bootcamp teachers. I talked to a handful of recruiters about my decision to move into the development world. This is the key information I got from them:

There is indeed a huge need for developers in the market.
Particularly, the Netherlands is a place in Europe where there is a developer shortage. Companies from this country go to other countries's job fairs to try and recruit talent. Me managing to easily find a job in Amsterdam supports this point.
A recruiter told me "the only thing you're missing is some kind of course certificate in your CV. It doesn't need to be official or expensive, anything does it". The reason? A certificate or course makes it easier for me to sell my CV to companies, given that I have no work experience as a developer. To them, it shows commitment.

In addition, I found a government-funded bootcamp in my city which costed me zero money (only a few coins spent on the coffee machine). The quality was very low. I completed it nonetheless and added it to my CV. All in all, the bootcamp was not a very useful way to spend my time and I'm not sure if it factored in getting a job in any significant way. My guess is it didn't, so I won't expand into it. There's not much of a take away here. Ultimately, what interviewees care most about is whether you can use front end tools or not. In sum, having a course of sorts in your CV is not going to hurt you, but you don't NEED it so don't let it be a blocker.

How do you know when you are ready to look for a job? I had no idea back then. In retrospective, I would say that the minimum to get a first job is:

Get well acquainted with HTML5, CSS3, JavaScript/ES6 and the fundamentals of one framework (React or Vue). This will take the longest time by far.
Feel comfortable with JS asynchronous code: that means Promises and async/await syntax.
Understand the basics about fetching data as JSON from external resources via APIs.
Goes without saying, but become familiar with an IDE, npm, git, github and some basic bash/unix commands. You'll get this knowledge while you learn the rest, so don't worry too much.

How did I look for a job?

Nothing special. I searched with LinkedIn, Indeed and Google, and in a couple of local job boards of the Netherlands and Denmark.

I was very careful in crafting my resume. One friend (thank you Miguel) had fine tuned his by getting feedback from many recruiters over the years, and I used the same structure. The advice I got could be summarized as follows:

Put the most relevant thing on top. Usually, relevant work experience is the most important thing. For your first job, it might be education instead. The most recent things should also go on top (always from newest to oldest).
Limit your CV to one single A4 page in one side. That will force you to remove the unimportant.
For each item in the CV (job experience, course...) use 2-4 bullet points to indicate what relevant things YOU (not your team) did. Be technical, brief and specific. Do not write long paragraphs, no one is going to read them.

I sent my resume as if I was shooting a machine gun, and I didn't use a motivation letter.

This is the resume I sent, in case you're curious (resume).

Finding a job was easy. My current job came out of spending one hour sending resumes. I only got a confirmation after 1 month, so I still put aside around 2 hours every 3 or 4 days to batch send resumes.

How did the job interviews go?

The 4 interviews I did followed the same structure.

The first part was about getting to know you. You are asked why you applied to the job, what's your background and what are your expectations. Companies like smart employees that have a "will do / will fix" positive attitude and that don't plan to leave the company in 6 months. Try to show these traits while you tell your story and in the way you communicate. For example, I was warned that the rental market in Amsterdam is hard to navigate. I immediately replied that I've had to look for a flat abroad in other occasions, and that I was sure I could figure that out.

The second part was the technical interview. The key here is that, if you have studied enough, this will simply be about showing what you already know well, so you should not be worried about it. I faced 3 types of technical interviews, either explaining the code of a project you have done, being asked technical questions, or getting a homework project. Let's look at each one by one:

Describing the code of one of your projects

I was asked to pick up any one of my recent projects, go through the code and explain it. At some point I was also asked to do a bit of code refactoring (improving your code for better readability and structure). In my opinion this is the most logical type of technical interview, because the fundamental knowledge is implied, and you are showing that you have technical knowledge. If you're going to face this interview, you must have learned well HTML, CSS, JavaScript ES6 and one frontend framework, and then you must have done 2 or 3 TINY projects with it. Think at the widget level more than at the full website level. This is the project I used in the interview: https://github.com/luismartinezs/studio-ghibli-books, as you can see it is very damn simple, but it was enough to show that I had a decent grasp of the fundamentals.

Technical questions

I was asked about ES6 JavaScript features. What does it mean adding "..." in front of an array or an object? What are the differences between a function declaration and an arrow function? This type of evaluation is a bit trickier in my opinion, because you may get lucky or unlucky with the questions and your knowledge might be either overestimated or underestimated as a consequence.

Homework projects

I was handed a project after an interview with Accenture. It took me around 20 hours to complete, and I only got a reply after one entire month (they replied that they wanted someone with more experience). This type of tests are usually asked for when the interviewer doesn't have technical knowledge and cannot evaluate you on the spot, so they pass the results of the test to the technical team for evaluation. I would suggest declining this type of tests. A company asking you to spend even 4 hours to solve a test just to evaluate you, rather than having someone from their technical team interview you, is asking you to waste your time. Only do the test if you have nothing better to do and you see the test as practice.

The bottom line is very simple: understand well the fundamentals, and the rest will follow.

What would I do differently?

There's very little I would have done different. There's only one way I could have gone faster: first, skip the part about jQuery in freecodecamp. After finishing the first 3 modules of freecodecamp, I would have skipped the bootcamp and begun building 2 or 3 sample projects with React. These projects should:

Look like something you might see in a website
They should be very simple, e.g. 2-3 days per project, which at your initial level will be the time you'll need to do a very simple widget from scratch
Need to incorporate proper calls to external APIs, using fetch.

Once I had these done, I would have begun looking for a job, as I would know everything required to perform decently well in an interview.

Thant's all for now. I'm happy to reply to any questions or comments that you may have.

Luis Martinez - Web Developer

How to Use Two GitHub Accounts on One Machine Without Switching Anything

Why is this so annoying?

Why is this three problems and not one?

Part 1: How do you set it up from scratch?

1. Make two SSH keys

2. Write ~/.ssh/config

3. Write a second SSH config, for work only

4. Write ~/.gitconfig

5. Write ~/dev/work/.gitconfig-work

6. Make commit signing actually verify

7. Make the gh CLI follow the folder too

8. Verify it, properly

Can an agent just do part 1 for me?

How do you add a third account?

Can an agent do part 2 too?

What if you move a scoped folder later?

What are the two traps?

Trap 1: why don't insteadOf rewrites chain?

Trap 2: why doesn't ssh -i override ssh_config?

What is that token doing in .git-credentials?

So what do you actually get?

Resources

I Tried to Make AI Output World-Class. Here's What Actually Happened.

The Question

The Hypothesis

Experiment 1: Code Debugging

Why This Domain

What the Data Said

The Real Finding

Experiment 2: Landing Page Copy

A Different Kind of Problem

The Routing Discovery

The Ceiling

The Key Insight

Experiment 3: UI Design

The Setup

Test 1: What Activates Better Design

Test 2: The Feedback Loop

The Structural Finding

What Three Experiments Actually Proved

Finding 1: The assumption was wrong

Finding 2: The expert's attempt to help can make things worse

Finding 3: Routing beats universal optimization

Finding 4: Architecture value is inversely proportional to model capability

Finding 5: The generation/revision loop is necessary but not sufficient for UI

What I'm Building Next

The Optimal Tech Stack, Architecture, and DevOps Setup for Building with Claude Code

How does Claude Code actually work?

First principle: why does information density matter?

So what is the stack?

TypeScript: why strict mode, no exceptions?

Frontend: why Astro + Vue + Tailwind?

Backend: why Hono + Bun + Drizzle + PostgreSQL?

How should you lay out the codebase?

Which phase are you in?

What goes in the shared packages?

What about DevOps?

Does the same principle apply to infrastructure?

Process management: why systemd over PM2?

Reverse proxy: why Caddy?

Hosting: why a VPS over a PaaS?

What is the SERVER.md for?

CI/CD: how much do you need?

What is the whole picture?

Reference: the stack in one table

Frequently Asked Questions

Why Astro + Vue instead of Next.js + React?

Does this architecture work with React or other frontend frameworks?

Should I use a single file for the entire backend even for a large app?

What if I want to use Prisma instead of Drizzle?

Why a VPS over Railway, Fly.io, or Vercel?

Does this work for mobile apps too?

PostgreSQL Function Syntax: Demystifying Anonymous vs. Tagged Dollar-Quoting

NUMBER 1

NUMBER 2

How to Make VS Code Search Find Specific Gitignored Files

The Plan

How to Do It

Explanation

2. Write `~/.ssh/config`

4. Write `~/.gitconfig`

5. Write `~/dev/work/.gitconfig-work`

Trap 1: why don't `insteadOf` rewrites chain?

Trap 2: why doesn't `ssh -i` override `ssh_config`?

What is that token doing in `.git-credentials`?