DEV Community: Chloe Zhou

Why My Model Wouldn’t Deploy to Hugging Face Spaces (and What Git LFS Actually Does)

Chloe Zhou — Sun, 11 Jan 2026 02:02:10 +0000

I trained a simple “is cat” image classifier using fastai and wanted to deploy a small demo on Hugging Face Spaces. I already had a working app.py and a trained model.pkl, so my plan felt straightforward: commit everything and push it to the remote Hugging Face repository.

At that point, I thought the hard part was already over. The model was trained, the demo worked locally, and deployment felt like it should be a routine step — commit, push, done.

That assumption didn’t last long.

What I Tried (and Why It Kept Failing)

When I tried to push the repository, Git rejected it with the following error:

remote: -------------------------------------------------------------------------
remote: Your push was rejected because it contains files larger than 10 MiB.
remote: Please use https://git-lfs.github.com/ to store large files.
remote: See also: https://hf.co/docs/hub/repositories-getting-started#terminal
remote:
remote: Offending files:
remote:   - model.pkl (ref: refs/heads/main)
remote: -------------------------------------------------------------------------
To https://huggingface.co/spaces/chloezhoudev/minima
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'https://huggingface.co/spaces/chloezhoudev/minima'

I could see what Git was complaining about — model.pkl was too large — but I didn’t really understand why this was a problem, or what “Git LFS” actually meant in practice. I had never used it before.

So I followed the instructions in the error message and tried to fix it step by step.

First, I installed Git LFS and set it up locally:

brew install git-lfs    # Install Git LFS (macOS via Homebrew)
git lfs install         # Initialize Git LFS and register Git hooks
git lfs version         # Confirm Git LFS installation

Then I told Git LFS to track my model file and committed it:

git lfs track "model.pkl"
git add model.pkl
git commit -m "Track model file with Git LFS"
git push

The push failed again — with the exact same error.

At this point, I was getting annoyed. Instead of really understanding how Git LFS worked, I tried to brute-force my way through the problem and asked ChatGPT for help. It suggested running the following command:

git rm --cached model.pkl

Then tracking the file with Git LFS again and committing:

git lfs track "model.pkl"
git commit -m "Store model file using Git LFS"
git push

Third attempt — same error. 😅

At this point, I seriously considered giving up. But since I already understood what I wanted to do, I felt I should at least understand why this wasn’t working. So I went back to ChatGPT one more time, and this time it suggested something very different:

git checkout --orphan clean-main
git add .
git commit -m "Initial deployment with Git LFS model"

git branch -M main
git push -f origin main

This time, the push finally worked.

Now that everything was deployed successfully, it was time to stop guessing and actually understand what had happened:

Why did Git keep rejecting my pushes?

What does Git LFS actually do?

Why didn’t git rm --cached help?

And why did creating an orphan branch fix everything?

What I Eventually Learned About Git and Git LFS

The first problem was that I didn’t actually understand why my push was rejected. Reading the error alone wasn’t enough — I just saw a message telling me to use Git LFS. It wasn’t until later that I learned Hugging Face repos enforce a pre-receive hook on their side that scans all commits being push to the remote (any commits not already on Hugging Face's servers) and rejects the push if any commit contains a file larger than 10 MiB.

Once that clicked, I began to think about how Git actually stores files and what role Git LFS plays. The simplest way to think about it is this:

A normal Git repository stores file contents as blob objects — each file you add is stored roughly at its original size in the history. For binary files, this is exactly what happens: Git takes the content and writes a blob object containing that data.
Git LFS replaces large files with pointer files and stores the actual big file contents separately on a dedicated LFS server. When you git add a file while Git LFS is enabled, Git LFS generates a small pointer and hands that pointer file over to Git to store in the repository. The large file itself gets uploaded to the Git LFS store instead.

💡 Key takeaway

So in my case, model.pkl was a large binary file.

Without Git LFS installed before it was ever added, Git simply stored it as a normal blob at full size.

That’s why my first push was rejected — the blob itself exceeded Hugging Face’s 10 MiB limit.

The next piece of the puzzle was the .gitattributes file that Hugging Face includes automatically when you create a Space repository. By default it contains a line like this:

*.pkl filter=lfs diff=lfs merge=lfs -text

This line tells Git which files should be tracked by Git LFS instead of by normal Git. However, for this to work, you must have Git LFS installed and initialized (git lfs install) before adding the file. Since I didn't have Git LFS set up when I first committed model.pkl, that rule had no effect.

Which brings us to the next question: what happened on the second push?

Even after I installed Git LFS and tracked the model file, the push was rejected again.

💡 Key takeaway

Installing Git LFS does not fix files that were already committed.

The old commit containing model.pkl as a normal blob was still in the history, and Hugging Face rejected the push because of it.

What about git rm — cached?

⚠️ Important

git rm --cached only affects future commits.
It does not remove files from your existing Git history.

The command removes the file from the staging area and stops tracking it in upcoming commits, while leaving the file intact in your working directory. However, it does nothing to delete the earlier commit where the large file was first added.

Because that original commit still contained model.pkl as a normal Git blob, the problematic file remained in the repository history — and Hugging Face continued to reject the push.

Finally, creating a new branch with no history (git checkout — orphan) fixed everything because it started with a clean slate that had no commits at all.

Once I added the files with Git LFS already configured, committed them, renamed clean-main to main (using git branch -M main), and force-pushed, the remote accepted it. There were no old blob objects in the history for the pre-receive hook to reject.

One more warning: using — orphan and especially git push -f is dangerous if multiple collaborators are using the same branch, because this permanently deletes all previous commits from the remote and can break everyone else's local copies. In my case, the Space repo was just for deployment, so this was fine, but it’s something to be careful about in team settings.

💡 Bonus: Git LFS isn’t the only option anymore

Hugging Face now also recommends git-xet, a newer backend designed specifically for large machine learning artifacts.

Both Git LFS and git-xet store large file content separately from Git's object database. The difference is that Git LFS stores complete files, while git-xet uses chunking and deduplication to handle incremental changes more efficiently — particularly useful for ML models that evolve over time.

After all that debugging, the model is finally deployed and working as expected.

You can try the live demo here.

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

A Real Performance Bug I Found and Fixed — Step by Step

Chloe Zhou — Sun, 27 Jul 2025 00:34:15 +0000

A few days ago, while working on a bug at work, I noticed something odd: after I fixed the bug, the default client name value in a dropdown component took almost 2 to 3 seconds to appear after the page loaded. That kind of lag is probably unacceptable to users, so I know I had to dig deeper.

Turns out, it was a performance issue.

We always hear advice like “don’t optimize prematurely” or “only solve performance problems when they exist.” Well, this was the first time I actually ran into one myself — and I think the debugging process is worth documenting.

In this post, I’ll walk through how I tracked down the cause of the slowdown. I can’t share the actual code or logs because of company policy, but I’ll reconstruct the process using pseudocode and reasoning steps. If you’re a frontend developer wondering how to approach a performance issue in a React app, I hope this gives you something concrete to take away.

If it’s not the API call, what is it?

When I first noticed the lag in how the client name appeared, my instinct was to check the Network tab. I opened DevTools and placed the network panel side-by-side with the UI so I could watch what was happening in real time. Sure enough, the API call to fetch client name came back quickly with a 200 OK. But even though the data returned fast, the client name still appeared in the dropdown field with a noticeable delay.

That made me pause — if it’s not the network latency, then what is? Could it be something in the frontend rendering cycle? Maybe Formik? Maybe context?

Here’s a bit of background. The client name is fetched from an API call and saved into the userInfo object, which lives in a global context. Formik pulls its initial values from this context. But initial values alone aren’t reactive — they don’t update just because the context does. So after the context gets the latest client name, I also call setFieldValue to make sure the form reflects the updated value.

At this point, I suspected the delay might be happening somewhere in that chain — from receiving the data to updating the form. So the question became: where exactly is the bottleneck?

Verifying data flow from API to form

My next step was to check how state updates propagated after the API call. The question was: after updating the context with the new client name, how exactly does that value reach the Formik form? I suspected a useEffect inside the page component (called Summary) might be responsible for syncing the values. So I added logs to verify the data flow step by step.

Step 1: Log inside Summary’s useEffect to confirm form syncing

useEffect(() => {
  console.log('[Summary] dealInfo.clientName effect triggered:', dealInfo?.clientName);

  if (dealInfo?.clientName?.trim()) {
    setFieldValue('summary.clientName', dealInfo.clientName);
  }
}, [dealInfo?.clientName]);

This log shows when the dealInfo.clientName value changes and triggers the code that updates the Formik field. It helps verify whether the effect runs immediately after the context updates — or if there’s any unexpected delay.

Step 2: Log right after receiving the API response

The clientName comes from an API call. Once the response is received, I update the global context via setDealInfo. To confirm that part was working correctly, I added a log right before updating the context:

setDealInfo(prev => {
  const updated = {
    ...prev,
    clientName: response.clientName, // from API response
  };
  console.log('[setDealInfo] triggered with:', updated);
  return updated;
});

This shows exactly when the client name arrives from the backend and enters the shared state.

Here’s what I saw:

On initial render, the useEffect ran quickly — but clientName was still empty, so setFieldValue was not called.

Then nothing happened for about 2–3 seconds.

After that delay, both the setDealInfo log and the useEffect log appeared almost at the same time.

The dropdown updated immediately after that.

This clearly shows that the 2–3 second delay was not due to slow state propagation or form logic. The delay happened before the context or form had any chance to react — meaning:

✅ the bottleneck was simply the API call being slow to return.

Measure the API Call Duration Precisely

Now that I suspect the API call might be slow, the next step is to confirm this with accurate timing logs.

I added these logs inside the loadClientDetails function — the one that calls the backend API to fetch client name:

console.time('[loadClientDetails] API call');

const response = await axios.get('/api/clientDetails', { params: { externalId } });

console.timeEnd('[loadClientDetails] API call');

setDealInfo(prev => {
  const updated = {
    ...prev,
    clientName: response.data.clientName,
  };
  console.log('[setDealInfo] triggered with:', updated);
  return updated;
});

This lets me measure exactly how long the API request takes from start to finish.

What I saw:

I ran the test 4 times, and the results varied wildly:

About 4000 ms (4 seconds)
About 8000 ms (8 seconds)
About 15000 ms (15 seconds)
About 1000 ms (1 second)

This confirmed without doubt that the API is the bottleneck and sometimes responds very slowly.

Minimal Fix: Show Loading Clearly, Don’t Wait in Confusion

The simplest and most effective fix was to explicitly handle the loading state on the Summary page.

Since the page already had a loading spinner for the segment data (fetched via useQuery), I added a similar one for the client name:

if (segmentIsLoading) {
  return <LoadingSpinner label="Loading segment..." />;
}

if (!dealInfo.clientName) {
  return <LoadingSpinner label="Loading client name..." />;
}

This way, users immediately see that data is loading — instead of staring at an empty field, wondering if something’s broken.

✅ Problem solved. Happy debugging — and happy summer. ☀️

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

Data Migration Design in a CLI Tool: From Local JSON to Cloud Database

Chloe Zhou — Sat, 05 Jul 2025 07:51:32 +0000

Introduction

I built a simple CLI tool that lets users take notes from the terminal. In version 1, there was no login and no cloud — notes were just saved to a local JSON file on the user’s computer.

That setup worked fine at the beginning. But as the tool grew, I added basic authentication and moved storage to the cloud (using Supabase), so users could access their notes across machines.

That change introduced a new problem:

What about users who already had notes saved locally?

If I just switched systems without thinking it through, they’d open the new version and find their notes gone.

This post explains how I handled that: designing a migration system that moves notes from the local file to the cloud — safely, clearly, and without making a mess.

Migration Means Moving Houses

When I was trying to understand how to approach migration, I asked AI for help. It gave me a useful analogy:

“It’s like moving houses.”

You have stuff in your old home — your local JSON file — and you want to move it into a new one — your cloud database. That sounds simple, but moving isn’t just about copying boxes from one place to another. It’s about making sure everything still works in the new place, nothing important gets lost, and the move itself doesn’t break anything.

Here’s what that actually means.

It’s not just copying — it’s cleaning up

In version 1, all notes were saved in a single JSON file on the user’s machine. That file might contain empty notes, malformed entries, or slightly inconsistent formatting.

But version 2 uses a structured cloud database (Supabase), where everything needs to follow a fixed schema. So before I can move anything, I need to sanitize the data:

Removing notes that are clearly empty or invalid
Making sure each note is shaped like an object with a content field, and a tags field, which is an array

In other words, before I move in, I clean the data up.

The data’s meaning also changes

In version 1, the tool assumed that one computer = one user. Notes were tied to the machine.

In version 2, notes are tied to a cloud user account. Now, you can log in from anywhere and access your notes. That’s a big shift in meaning:

The same note is now “owned” by a user, not a device
Access is controlled by authentication, not file access
Notes can now live across machines, not just one

So part of the migration is not just “moving files,” but changing what the data represents.

Users need to know what’s happening

You don’t move into a new house without telling your friends. Migration needs to be transparent too.

If I silently switch to the cloud without warning, users might open the new version and think all their notes are gone. That’s bad UX. So I designed the migration to include:

A check to see if old notes exist
A prompt letting users choose whether to migrate
Clear feedback on what was migrated and what wasn’t

Good UX means telling users what’s going on, not making them guess.

Bringing it together

Migration isn’t just a file transfer. It’s three things working together:

Data transformation: Cleaning and reshaping the notes so they can live in a database.
State change: Notes now belong to a cloud account, not just a local machine.
User experience: Letting users know what’s happening and giving them control.

That’s what it really means to move from version 1 to version 2. It’s not just a new backend — it’s a change in what data is, who owns it, and how users interact with it.

The Migration Strategy: Five Steps

Once I understood what this migration really meant, I broke the process down into five concrete steps. Each step solves a specific problem, and together, they ensure the user’s data moves safely from version 1 to version 2.

Detection — Does the user have old data?

Before running any migration, I need to know whether there’s anything to migrate.

The version 1 CLI tool stored notes locally in a known file path. So the first step is to check if that file exists on the user’s machine.

If the file isn’t there, then this user is either new or never saved anything — no migration needed.

Safety — Make a backup before touching anything

Even if migration is simple, data loss is never acceptable.

Before doing anything else, I make a full backup of the original JSON file. This way, if something goes wrong during migration — or if the user just wants to revert — they can recover their data.

This is a simple but important rule: never destroy the original source.

Translation — Clean up and reshape the data

The local notes file was flexible. In version 2, the data needs to follow a specific structure to be accepted by the cloud database.

So before inserting anything, I sanitize each note:

Remove empty notes (e.g. whitespace-only)
Skip notes with missing or malformed fields
Make sure each note has the expected shape

This is the “translation” step: same ideas, but restructured to fit the new format.

Transfer — Save the cleaned notes to the cloud

After cleanup, I use the database utility functions I already built (like createNote) to send each note to Supabase. These functions are the same ones used by the app during normal use — so the migrated notes behave exactly like new ones.

If any note fails to save, I don’t crash the whole process. I log it, skip it, and continue.

Verification — Show the result to the user

Once the migration runs, I want to tell the user exactly what happened.

So I track:

How many notes were found
How many were skipped
How many were successfully migrated

The CLI shows a short summary at the end, so the user knows whether everything worked — or if they need to take a closer look.

Why this approach works

This strategy covers both data integrity and user experience:

Each step is small, focused, and testable
If anything fails, users don’t lose their data
Users are never left guessing what just happened

UX Considerations

I didn’t want the migration to interrupt users. If they don’t have old data, it should just be invisible.

If they do, they should get a clear path — but only when they need it.

It only checks once, during setup

When the user runs note setup, the CLI checks if there’s a local JSON file from version 1.

If it exists, the CLI shows this:

Legacy notes detected!
You can run:
  notes migrate check   # See what can be migrated
  notes migrate         # Perform the migration

If there’s no local data, nothing happens. No prompt, no message.

This avoids showing unnecessary stuff to new users.

Output is simple and direct

When note migrate runs, the CLI prints something like:

Found 8 local notes.
6 migrated successfully.
2 skipped (empty or invalid).

It doesn’t hide anything. If a note fails, it’s listed and skipped.

The point is to tell users exactly what was moved, and what wasn’t.

It won’t run again once migration is done

After a successful migration, the CLI deletes the old JSON file and archives a copy in a separate folder.

So if the user runs note migrate again, the tool won’t find anything to migrate — it just says:

No legacy notes found. Nothing to migrate.

There’s no per-note tracking. Migration is a one-time thing.

If something goes wrong, the backup is still there.

Key Principles Behind Good Migrations

When I put together this migration logic, I mostly followed a few basic rules.

Back up first

Before doing anything, the CLI makes a copy of the notes file (e.g. db-backup.json in the same folder. If something breaks, the original file is still there.

If something fails, keep going

One bad note shouldn’t block everything.

The CLI skips anything invalid, and finishes what it can.

No need to roll back or crash the whole thing.

Say what’s happening

This isn’t a silent background process.

If notes are being moved, the CLI tells you how many it found, how many migrated, and what got skipped.

Let the user choose

Migration only runs if the user decides to.

The CLI checks once during note setup, but it’s up to the user whether to run note migrate.

No auto-magic.

Safe to run more than once

If the migration already happened, running it again just says:

No legacy notes found. Nothing to migrate.

No side effects, no surprises.

Conclusion

Working on this migration helped me see that data migration is more than just a technical task. It touches multiple areas — technology, product design, and user experience.

Even for a lightweight CLI tool, data needs to be treated as a valuable user asset. Losing data means losing user trust, and that’s not easy to regain.

A good migration might run only once — but how it’s designed says a lot about how much you care about your users.

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

Error Handling in CLI Tools: A Practical Pattern That’s Worked for Me

Chloe Zhou — Thu, 19 Jun 2025 02:00:17 +0000

I’ve been building a small CLI tool recently to help manage personal notes from the terminal. It’s a simple project, but adding features like persistent user sessions and database access made me think more seriously about error handling.

In particular, I wanted to find a balance between surfacing helpful messages to users while keeping my codebase clean and predictable. This post documents the approach I landed on, why I chose it, and how it plays out in a few real command implementations.

Why Error Handling Matters in CLI Tools

When designing error handling for a CLI tool, my goal was to make sure that any failure a user runs into is:

Human-readable
Actionable
Context-aware

To get there, I explored common error handling patterns in async JavaScript — specifically how to structure error throwing in utility functions versus catching in command handlers, and how to categorize different types of errors. I ended up with an approach that distinguishes between expected errors, system errors, and business logic errors.

Two Common Patterns

Pattern 1: Throw Errors (Recommended for CLI)
Pattern 2: Return Error Objects

Let me show you what they look like in practice.

Pattern 1: Throw Errors (Recommended for CLI)

This pattern has low-level functions throw errors when something goes wrong. The errors bubble up to the command handler, which catches them and displays a friendly message.

export const saveUserSession = async (user) => {
  try {
    await ensureUserDir();
    const sessionData = { id: user.id, username: user.username, loginTime: new Date().toISOString() };
    await writeFile(USER_SESSION_PATH, JSON.stringify(sessionData, null, 2), 'utf-8');
    return sessionData;
  } catch (error) {
    throw new Error(`Could not save user session: ${error.message}`);
  }
};

The command handler then handles all errors in one place:

.command('setup <username>', 'Setup user', {}, async (argv) => {
  try {
    const user = await findOrCreateUser(argv.username);
    await saveUserSession(user);
    console.log(`✅ Successfully logged in as: ${user.username}`);
  } catch (error) {
    console.error('❌', error.message);
    process.exit(1);
  }
});

This approach keeps the command code clean and focused. You only deal with errors once, and you get to present consistent messages.

Pattern 2: Return Error Objects (Alternative)

Here, low-level functions catch errors themselves and return objects indicating success or failure.

export const saveUserSession = async (user) => {
  try {
    await ensureUserDir();
    const sessionData = { id: user.id, username: user.username, loginTime: new Date().toISOString() };
    await writeFile(USER_SESSION_PATH, JSON.stringify(sessionData, null, 2), 'utf-8');
    return { success: true, data: sessionData };
  } catch (error) {
    return { success: false, error: `Could not save user session: ${error.message}` };
  }
};

Then every caller must check the returned object explicitly:

.command('setup <username>', 'Setup user', {}, async (argv) => {
  const userResult = await findOrCreateUser(argv.username);
  if (!userResult.success) {
    console.error('❌', userResult.error);
    process.exit(1);
    return;
  }

  const sessionResult = await saveUserSession(userResult.data);
  if (!sessionResult.success) {
    console.error('❌', sessionResult.error);
    process.exit(1);
    return;
  }

  console.log(`✅ Successfully logged in as: ${userResult.data.username}`);
});

While this pattern makes errors explicit, it can lead to repetitive and verbose code, especially in command handlers.

Why I Prefer Pattern 1 (Throw Errors)

This pattern feels like a better fit for CLI tools:

Low-level modules throw meaningful errors when things go wrong
Errors bubble up automatically through the call stack
Top-level command handlers catch them once and show user-friendly messages
Exit codes tell the shell that something failed

This keeps responsibilities clear: helper functions focus on their job, command handlers focus on user communication.

Error Handling Strategy by Type

1. Expected "Errors" (Not Really Errors)

Some conditions aren't really errors — they're just normal edge cases that we expect to happen occasionally. For example, if there's no session file, that simply means the user hasn't logged in yet.

export const getUserSession = async () => {
  try {
    await access(USER_SESSION_PATH);
    const sessionData = await readFile(USER_SESSION_PATH, 'utf-8');
    return JSON.parse(sessionData);
  } catch (error) {
    if (error.code === 'ENOENT') {
      return null; // File doesn't exist = no session (EXPECTED)
    }
    throw error; // Unexpected error
  }
};

2. System Errors

These usually come from the underlying platform — e.g. Node.js APIs, the file system, or corrupted files. They're rare but should be surfaced with context.

export const saveUserSession = async (user) => {
  try {
    await writeFile(USER_SESSION_PATH, JSON.stringify(sessionData));
    return sessionData;
  } catch (error) {
    // Transform technical error into user-friendly message
    throw new Error(`Could not save user session: ${error.message}`);
  }
};

3. Business Logic Errors

These happen when users violate your application's rules or skip required steps. The system works fine, but the user needs to do something differently.

export const requireUserSession = async () => {
  const session = await getUserSession();
  if (!session) {
    // This is a business rule violation
    throw new Error('No user session found. Please run "note setup <username>" first.');
  }
  return session;
};

The Key Insight

Notice how each type gets handled differently:

Expected conditions → Return null or default values, don't throw
System errors → Wrap with context, then throw
Business logic errors → Throw with clear instructions for the user

This approach means your command handlers can catch everything with one try/catch, but users get appropriate messages for each situation.

Complete Error Flow Example

Let's walk through how the full error handling flow works — from throwing to catching to presenting.

1. Low-Level: Throw with Context

export const clearUserSession = async () => {
  try {
    await unlink(USER_SESSION_PATH);
    return true;
  } catch (error) {
    if (error.code === 'ENOENT') {
      return true; // File doesn't exist = mission accomplished anyway
    }
    throw new Error(`Failed to clear session: ${error.message}`);
  }
};

At this level, we care about what failed, not how to explain it to the user. We handle the expected case (no file) and throw system errors with context.

2. Business Logic Layer: Enforce Rules

export const requireUserSession = async () => {
  const session = await getUserSession();
  if (!session) {
    throw new Error('No user session found. Please run "note setup <username>" first.');
  }
  return session;
};

This enforces a business rule: "You must be logged in to logout." We throw a specific message that tells the user exactly what to do.

3. Command Layer: Catch + Present

.command('logout', 'Clear current user session', {}, async () => {
  try {
    const session = await requireUserSession(); // Business rule check
    await clearUserSession(); // Low-level operation  
    console.log(`✓ Logged out ${session.username} successfully.`);
  } catch (error) {
    console.error('❌', error.message);
    process.exit(1);
  }
});

This is the one place where we actually talk to the user. We catch everything, show a friendly message, and exit with a non-zero code to signal failure.

Now it's a true connected flow: check session → clear session → report success, with proper error handling at each layer!

Best Practices Summary

Low-level functions: throw meaningful errors with context, handle expected cases gracefully (like ENOENT → return success)
Expected cases: don't throw for normal situations — return appropriate values instead
Business logic violations: throw with clear, actionable messages that tell users what to do next
Command handlers: catch all errors in one place, present friendly feedback, and call process.exit(1) for failures
Error messages: be specific and actionable — tell users exactly what went wrong and how to fix it
Exit codes: use process.exit(1) so scripts and shells know something failed

Try It Out (And Stay Tuned)

The error handling strategies in this post are part of a broader upgrade I'm working on for my CLI tool czhou-notes-cli. The current version stores notes locally and is already usable.

You can try it now via:

npm install -g czhou-notes-cli

Right now I'm actively improving it — adding things like database support and smoother command experience — and this error handling refactor is just one piece of the puzzle.

If you give it a try and have any ideas or suggestions, feel free to open an issue or just let me know — I'd love to hear your thoughts!

Thanks for reading 😊

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

Deploying Express + TypeScript + Prisma to Render (2025): What Went Wrong (and How I Fixed It)

Chloe Zhou — Wed, 04 Jun 2025 00:07:48 +0000

When I deployed my Express + TypeScript + Prisma backend to Render, I didn’t expect to spend an entire afternoon chasing down one error after another — but that’s exactly what happened. This post is a personal log of all the unexpected problems I hit, what they actually meant, and what I did to get things working again.

I’m writing this down in case someone else (or future me) runs into the same stack of issues and needs a sanity check.

🔴 Error 1: `process` and `console` not found in TypeScript

💥 What was the error?

During the build, I saw this in the logs:

Cannot find name ‘process’.
Cannot find name ‘console’.

TypeScript didn’t seem to recognize basic Node.js globals. I thought this was weird — these should be available by default, right?

🧪 What I tried

I added the following to my tsconfig.json:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

…only to be greeted with:

Cannot find type definition file for 'node'

I had @types/node installed — but it was under devDependencies.

✅ What actually fixed it

Turns out Render doesn’t install devDependencies during production builds by default. Once I moved @types/node to dependencies, the build succeeded.

npm install @types/node --save

✔️ Lesson learned: If your app builds before running (like most TypeScript setups), your build-time tools and types must be in dependencies, not devDependencies.

🔴 Error 2: Cannot find index.js on Render

💥 What was the error?

Another build, another facepalm:

Error: Cannot find module '/opt/render/project/src/index.js'

Render was trying to start my app using node index.js, but my compiled code lived in dist/index.js.

🧪 What I tried

I updated package.json:

{
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Still didn’t work.

✅ What actually fixed it

Render’s Start Command was still set to node index.js in the Dashboard.

Once I changed it to:

npm start

…everything clicked into place.

✔️ Lesson learned: Your local scripts don’t override what Render runs. Double-check the Start Command and Build Command fields in the Render Dashboard.

🔴 Error 3: @prisma/client did not initialize

💥 What was the error?

@prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.

At this point, I wasn’t even surprised anymore.

🧪 What I tried

I checked my build script. It was just:

"build": "tsc"

…but Prisma Client needs to be generated before TypeScript compiles the code that imports it. Oops.

Also, I noticed my schema.prisma had a custom output path like this:

generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/prisma"
}

✅ What actually fixed it

I updated the Prisma generator config to use the default output path (which lives inside node_modules/.prisma/client):

generator client {
  provider = "prisma-client-js"
  output   = "../node_modules/.prisma/client"
}

I updated the build script to ensure Prisma Client gets generated before compilation:

"build": "prisma generate --no-engine && tsc"

I also updated the import to:

import { PrismaClient } from '@prisma/client';

✔️ Lesson learned: Prisma Client must be generated before compilation. Also, using the default output path avoids a lot of edge cases — especially when deploying.

✅ Final Checklist (So I Don’t Forget Again)

Here’s a checklist of everything I ended up fixing:

Move @types/node from devDependencies → dependencies
Use start: node dist/index.js in scripts
Set Build Command to npm run build on Render
Set Start Command to npm start on Render
Use prisma generate before tsc in your build step
Avoid customizing Prisma output unless you have to — use the default node_modules/.prisma/client
Use --no-engine with prisma generate if you’re deploying or using Prisma Accelerate

One last thing

If you’re here because your Render build failed with some weird Prisma or TypeScript error — you’re not alone. It’s usually something small, just hiding in plain sight.

Hope this helps someone else. If you’ve run into other gotchas with this stack, feel free to share — I’d be happy to learn from your debugging too.

🛠 Tech Stack / Environment

Node.js: 18.20.5
Express: 5.1.0
TypeScript: 5.8.3
Prisma: 6.6.0
@prisma/client: 6.6.0
ts-node: 10.9.2
Render deployment: May 2025

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

What I Learned from My First Legacy Frontend Project

Chloe Zhou — Thu, 01 May 2025 07:17:01 +0000

This was my first time taking over a legacy frontend codebase - one that had been around for over five years.

The system was built with React 16.8 and relied heavily on class components. This code was tightly coupled, hard to follow, and even harder to extend. Some components had over thousand lines, with tangled logic and strong dependencies. If you change one thing, you couldn't be sure what else might break.

My task sounded straightforward: support a new business type with some custom fields and a different layout. But as I dug in, I realized it was more than just adding a few inputs. I had to reuse existing logic, introduce new behaviors, and make sure I didn't break anything already in use. It wasn't just development - it was kind of software surgery. Every change had to be precise. One wrong move, and things could break in ways you wouldn't expect.

This article doesn't dive into technical implementation, nor is it meant to complain about how messy legacy code can be. Instead, I want to document the three main pitfalls I encountered during my first legacy delivery - and the three key lessons I learned from them.

Pit #1: Don't Refactor Logic Without Fully Understanding the System First

Before I started the actual delivery of the new feature, I had a bit of extra time, so I decided to take the opportunity to familiarize myself with the module that I was about to modify. As I dug into the code, I noticed that some parts of the logic had very tight coupling. This made me think that it might be worth refactoring those sections as part of the preparation for the upcoming delivery. It seemed like a good idea at the time.

But I made a crucial mistake. I didn't have a complete understanding of the logic I was about to refactor. I thought I had a good grasp of it, but in reality, I didn't know the ins and outs of the code well enough. I didn't fully comprehend how it interacted with other parts of the system, what its true dependencies were, or how the inputs and outputs were structured.

Here's the key lesson: when you're refactoring code, you need to have 100% clarity on the logic you're working with. That doesn't mean understanding the entire system, but understanding your specific module - what dependencies it has, and what its inputs and outputs are - is essential.

Some of you might be thinking, "Why not just write tests first, and then refactor? Isn't that what TDD is for?" Well, yes… and no. While TDD is a widely recommended approach, and it could certainly help in a clean, modern codebase, the reality is quite different when you're dealing with a legacy system like the one I was working with. And let's be honest - who really enjoys writing tests?

After I refactored the code, I found that the behavior had changed unexpectedly. This made it difficult for me to trace back the original logic and behavior, as I had unintentionally altered it without fully understanding it in the first place.

To fix this, I needed to identify where the issue came from. I ran tests in my UAT environment, where I could compare the new behavior with the original. By doing this, I was able to debug the inconsistencies between what was happening in my local development environment and the behavior in the higher environment. This process helped me pinpoint where my logic change had led to unexpected outcomes, and I was able to correct the mistake.

So the core lesson here: never blindly refactor code without fully understanding the business context and logic behind it. Even if it seems like a "pure UI improvement", it can have unintended consequences that affect the overall system.

Pit #2: Don't Wait Until You Fully Understand the System to Start Refactoring - Embrace the "Incremental Approach"

While it's essential to have a solid understanding of the logic you're working with before making changes (as discussed in the first pit), there's a fine line between being cautious and getting stuck in analysis paralysis. The key lesson here is: don't wait to understand every single detail of the system before taking action. Instead, aim for an incremental approach - make small, controlled changes and expand your understanding as you go.

The reality is that achieving a comprehensive understanding of the entire system is nearly impossible, especially when working with complex legacy code. The system is intricate, with too many moving parts, and expecting to grasp it all upfront can lead to endless analysis with little actual progress.

So, what's the solution?

Find a reasonable entry point where you can start making small, manageable changes - this will help build your confidence and gradually expand your understanding. For example, when approaching frontend tasks, it's common practice to start with static UI. Static UI tends to have simpler, more isolated logic, making it a good entry point for understanding the structure of the code.

Take a look at how the static UI is built. Focus on things like the render function in your React components, which handles the visual part of the UI. This part is generally less complicated, so it gives you a solid foundation to start making small adjustments. Once you're comfortable with that, you can move on to more interactive parts of the code, tackling them one step at a time.

This incremental approach works especially well with legacy systems. Trying to understand everything upfront before making any changes can slow you down unnecessarily. Instead, by taking it step-by-step, you can start making progress right away and build your understanding as you go.

Pit #3: Migrating Lifecycle Methods Isn't Just About Replacing Them

When I took over this legacy code, I was already accustomed to React 18 and functional components with hooks, so I wasn't very familiar with class components and their lifecycle methods - especially the ones like componentWillReceiveProps, which is deprecated, and getDerivedStateFromProps, which is the recommended alternative. My initial instinct was to replace these deprecated methods with their newer counterparts. But soon, I realized that migration isn't just about swapping one lifecycle method for another.

React provides alternatives, such as getDerivedStateFromProps for componentWillReceiveProps. However, migrating lifecycle methods isn't as simple as finding a "replacement." Each lifecycle method is triggered at specific points in the component's lifecycle and serves particular use cases. Understanding how and when each method is invoked is critical. Without this understanding, you risk introducing new issues or inconsistencies.

Take my specific case, for example. In the project I was working on, componentWillReceiveProps was in use, and my goal was to migrate it to getDerivedStateFromProps. The reason for this migration was that the new requirement was to update the component's state based on new props, which made getDerivedStateFromProps a suitable alternative. However, there's a catch - componentWillReceiveProps and getDerivedStateFromProps have different behaviors and usage patterns.

After analyzing the existing code, I realized that componentWillReceiveProps was already being used to update the state based on new props, but it was updating different properties of the state. Given that the new requirements aligned with what getDerivedStateFromProps is intended for - updating state based on new props - I saw an opportunity to merge the new requirements with the existing logic. By doing this, I was able to combine the old logic with the new behavior, making the migration smoother.

Lesson learned: Migrating lifecycle methods isn't just about replacing deprecated methods with the new ones React provides. It's about understanding the logic behind each method, when it's triggered, and whether it fits your specific needs. In my case, I needed to ensure that the new and old logic could be combined effectively before proceeding with the migration.

Respect the System, Respect the Unknown

Legacy systems aren't monsters. They've grown over time to support real, often messy business needs. The complexity you see is rarely accidental - it reflects years of decisions, constraints, and trade-offs.

After delivering my first feature on this project, I started to see things more clearly. Respecting the system doesn't mean staying hands-off - it just means knowing what's already there, and being cautious about what might break when you change it. You can still refactor boldly, but only if you understand the impact.

When things feel overwhelming, it helps to find one small, solid starting point. Something you're sure about. From there, piece by piece, you build up enough context to move forward. That's how I've learned to work with legacy code - not by fully mastering it first, but by finding my footing one step at a time.

What about you? Have you worked on legacy projects? Let me know below!

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

How I Built Schedulicious: A Meal Planning Web App

Chloe Zhou — Mon, 17 Feb 2025 07:39:20 +0000

How it Started

I joined Chigu during my job search because I wanted to stay productive, sharpen my skills, and gain more hands-on experience working in a team.

Job hunting can be a unpredictable process, and instead of waiting around, I saw Chigu as the perfect opportunity to build something meaningful while collaborating with others.

Looking back, it turned out to be one of the best decisions I made—not only did I improve my technical and teamwork skills, but I also got to experience the full process of bringing a project from 0 to 1.

What We Built

The project is a meal planning tool designed to help managers efficiently create weekly menus for employees.

Key Features:

One-Click Menu Generation – Instead of manually selecting meals, managers can generate a balanced menu with a single click.
No Repeated Meals – The system ensures that each day’s dish is unique, preventing repetition throughout the week.
Easy Regeneration – If the results aren’t satisfactory, a “regenerate” button allows them to create a new menu instantly.
Export Functionality – Users can save and track meal plans in PDF or Excel format for easy reference.

From 0 to 1

Each team receives a product spec with predefined features, but it’s up to us to break them down, plan the implementation, and bring the product to life.

Leading the Project

Our team was unique—no project manager, product owner, or UI/UX designer—just developers. Seeing the opportunity to lead in the absence of a project manager, I volunteered to take on the role. It felt like a perfect challenge to organize the team and drive the project forward.

I kicked off the project by planning the initial meeting: setting an agenda, defining each team member’s tasks, and ensuring we were aligned on the outcomes. Thanks to this preparation, the meeting was productive, and we defined our MVP features and roles for the upcoming sprint.

Building the Product Backlog

In sprint 2, I took on the responsibility of creating a Product Backlog, which is usually handled by a Product Owner. I broke down the MVP features into epics, user stories, and tasks, creating templates to ensure everyone was aligned.

This process made me realize how essential the backlog is as a roadmap for the team. It wasn’t easy—understanding each feature, defining clear acceptance criteria, and avoiding repetition was a challenge. But as I worked through it, I gained a clearer understanding of how each feature impacts the end user.

One instance where I exercised product thinking was when I adjusted the feature flow based on my own understanding of user needs and how they would interact with the product to ensure a smooth experience.

Unlike in more structured environments where backlogs are typically fixed, I had the freedom to adapt the “HOW” during development, tailoring the features to better suit user needs. This process was both challenging and rewarding, sharpening my product thinking and development skills.

The Tech Stack

For this project, we didn’t have to worry about a backend since we were working solely with a dish API. Therefore, I chose React as the core of the tech stack, paired with Vite as the build tool to ensure fast development and smooth hot reloading.

For state management, I initially considered Context API and Zustand, ultimately choosing Zustand for the following reasons:

Our use case was simple but involved sharing state across multiple routes (e.g., allergies and weekly menus).
Zustand provides built-in middleware for local storage persistence, which saved us time and effort in implementing our own solution.
Out of the box, Zustand offers better performance, as it updates only the relevant parts of the state without unnecessary re-renders.
Zustand is easier to scale. Should we need to manage more complex states, such as loading or error handling, or handle more sophisticated logic in the future, it can grow with the project.

UI/UX Design

For this MVP, I aimed to create a clean, modern, and easy-to-navigate UI that would allow users to start using the tool immediately without the need for a sign-in or sign-up process. The goal was to minimize friction and make the user experience as seamless as possible.

A bright color palette, chosen for its ability to convey a sense of openness and clarity, sets the tone for the UI, thanks to our talented UI/UX designer. She laid the foundation for the design, and I tailored the UX to suit the users’ needs.

Designing the Swap Feature

One of the key features I focused on was ensuring users could easily swap dishes if they weren’t happy with their selection.

Initially, I considered allowing users to search through a large list of dishes, which could be intuitive but might not be the most efficient way to save their time. Instead, I designed a modal popup that presents five recommended replacement dishes.

These dishes are randomly generated from the available dish database, ensuring no repeats with the current weekly menu. Offering five options strikes a balance between providing enough variety and avoiding overwhelming the user. I believe this design choice helps users make quick, informed decisions without limiting their options.

Here’s the UI in action:

Overcoming Challenges and Delivering the Project

Just two sprints into the project, our team faced some challenges when two members became less active, and our UI/UX designer, who was also expected to contribute to development, had to step back.

By the time we were ready to dive into the development phase, it was just me. Although I briefly considered quitting, I decided to push forward and deliver the project on my own.

I focused on core feature development and refining the user experience. Despite the challenges, I was able to successfully complete the product!

I shared my full journey on Twitter.

// Detect dark theme var iframe = document.getElementById('tweet-1890735259190440170-769'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1890735259190440170&theme=dark" }

Special thanks to @numulaa for laying the foundation for the design, and you can find her work here on GitHub.

Check out the project!

I’m excited to share that this project is open source! You can explore the code, contribute, or just check it out on GitHub. If you found it useful or interesting, feel free to give it a star ⭐—it would mean a lot!

Try the live demo or watch the YouTube walkthrough to see it in action!

💬 Got feedback? I’d love to hear your thoughts! Feel free to open an issue on GitHub or drop me a message.

I’ll continue improving and iterating on it—stay tuned for updates! 🚀

If this helped you, I write about real dev problems at chloezhou.dev — you can subscribe to get new posts by email.

DEV Community: Chloe Zhou

Why My Model Wouldn’t Deploy to Hugging Face Spaces (and What Git LFS Actually Does)

What I Tried (and Why It Kept Failing)

What I Eventually Learned About Git and Git LFS

A Real Performance Bug I Found and Fixed — Step by Step

If it’s not the API call, what is it?

Verifying data flow from API to form

Step 1: Log inside Summary’s useEffect to confirm form syncing

Step 2: Log right after receiving the API response

Here’s what I saw:

Measure the API Call Duration Precisely

What I saw:

Minimal Fix: Show Loading Clearly, Don’t Wait in Confusion

Data Migration Design in a CLI Tool: From Local JSON to Cloud Database

Introduction

Migration Means Moving Houses

It’s not just copying — it’s cleaning up

The data’s meaning also changes

Users need to know what’s happening

Bringing it together

The Migration Strategy: Five Steps

Detection — Does the user have old data?

Safety — Make a backup before touching anything

Translation — Clean up and reshape the data

Transfer — Save the cleaned notes to the cloud

Verification — Show the result to the user

Why this approach works

UX Considerations

It only checks once, during setup

Output is simple and direct

It won’t run again once migration is done

Key Principles Behind Good Migrations

Back up first

If something fails, keep going

Say what’s happening

Let the user choose

Safe to run more than once

Conclusion

Error Handling in CLI Tools: A Practical Pattern That’s Worked for Me

Why Error Handling Matters in CLI Tools

Two Common Patterns

Pattern 1: Throw Errors (Recommended for CLI)

Pattern 2: Return Error Objects (Alternative)

Why I Prefer Pattern 1 (Throw Errors)

Error Handling Strategy by Type

1. Expected "Errors" (Not Really Errors)

2. System Errors

3. Business Logic Errors

The Key Insight

Complete Error Flow Example

1. Low-Level: Throw with Context

2. Business Logic Layer: Enforce Rules

3. Command Layer: Catch + Present

Best Practices Summary

Try It Out (And Stay Tuned)

Deploying Express + TypeScript + Prisma to Render (2025): What Went Wrong (and How I Fixed It)

🔴 Error 1: process and console not found in TypeScript

💥 What was the error?

🧪 What I tried

✅ What actually fixed it

🔴 Error 2: Cannot find index.js on Render

💥 What was the error?

🧪 What I tried

✅ What actually fixed it

🔴 Error 3: @prisma/client did not initialize

💥 What was the error?

🧪 What I tried

✅ What actually fixed it

✅ Final Checklist (So I Don’t Forget Again)

One last thing

What I Learned from My First Legacy Frontend Project

How I Built Schedulicious: A Meal Planning Web App

How it Started

What We Built

Key Features:

From 0 to 1

Leading the Project

Building the Product Backlog

The Tech Stack

UI/UX Design

🔴 Error 1: `process` and `console` not found in TypeScript