Around mid-2025, I was looking for ways to increase my income and had long wanted to try a side project that could both train me and bring in some extra money.

Earlier that year, I started following a creator on Xiaohongshu (a Chinese social media platform) who shared videos about running an Etsy shop selling digital products and templates. He talked about using AI to create virtual products, and his content made me think: "I could do that too." Digital products don't require inventory, rely mostly on creativity, and have very low upfront costs. I already used AI tools frequently, so I felt confident I could make something work.

These two motivations overlapped — financial pressure and outside inspiration — and together they pushed me to officially start my Etsy experiment in mid-2025.

Before committing, I did some market research: I studied best sellers and star sellers on Etsy, looking at review counts, prices, product images, and descriptions. I tried to estimate their sales by comparing review counts to total sales (reviews typically account for less than 10% of sales). My goal was to determine whether this niche could realistically meet my income target.

I also defined my target users: people who needed financial awareness tools — freelancers, self-employed individuals, or anyone wanting to track their personal budgets.

First action: choosing the "budgeting printable template" niche

I decided to start with printable, downloadable templates — monthly budgets, expense trackers, and similar tools. My main advantage was being able to code. I didn't know design tools like Canva, so my first products were built entirely through code.

My first product was actually a bundle: a Monthly Budget Planner, an Expense Tracker, a Bill Planner, a Debt Tracker, and a Savings Goals template — designed to work as a connected system that helps users understand their spending patterns.

The Emergency Fund Booster was designed to make saving purposeful. People often struggle to save when they don't know why they're saving. I wanted to give their savings meaning — preparing for layoffs, unexpected medical bills, or other emergencies.

Technical path, tool shift, and the Google Sheets product line

Initially, I relied entirely on coding to build my templates. But I quickly realized I was spending far more time maintaining code than improving designs or expanding my product line.

So I tried designing a product in Canva — and found it was much easier and visually cleaner. The colors, fonts, and layouts looked more appealing. I also created multiple color schemes for users to choose from.

After shifting my mindset toward design rather than pure logic, I explored a niche that better reflected my technical strengths: Google Sheets templates. Google Sheets let me combine coding (via Apps Script) with small automation features, making templates more practical and user-friendly.

It took about two weeks to build my first Google Sheets product from concept to final version. During that process, I also learned video editing — static images couldn't effectively showcase how the Sheets worked. I started recording my screen, editing clips, and turning them into marketing videos. That was a personal breakthrough: combining coding, product thinking, and content creation in one project.

Product launch, SEO, and early data strategy

My upload process was: use eRank to find high-volume, low-competition keywords, feed those into ChatGPT to generate titles and descriptions, and design product images in Canva.

Following advice from the creator I'd been watching, I didn't focus heavily on analytics early on. Etsy's algorithm doesn't give new shops with few listings much visibility, so I focused on building up my product count first.

What I didn't yet understand was marketing logic: what kind of image or description actually drives conversions, or how to effectively communicate a product's value in a listing. Those gaps only became clear later.

Expanding listings and taking data seriously

Once my total listings reached around ten, I started checking analytics seriously — and the results were discouraging.

Unlike the printable products, which got at least a few daily impressions, the Google Sheets products had almost none. Zero visibility. The algorithm wasn't distributing them at all.

Seeing that data made me doubt everything: Was the product flawed? Was my positioning wrong? Was my whole approach misguided?

Adjustments and outcomes

Faced with nearly zero organic traffic, I first overhauled all my Google Sheets titles, tags, and descriptions with AI's help, then waited about a week. Nothing changed.

Next, I shifted from broad "high search, low competition" keywords to more specific ones that captured my product's unique value. I also set up a 30% off limited-time discount, hoping to attract my first buyers and reviews — which might trigger the algorithm to show my listings more.

I noticed a small amount of traffic coming from Pinterest, so I created an account and started posting pins for my Google Sheets products. The pins got a few impressions but almost no clicks. Overall Etsy traffic stayed extremely low.

Each time I made adjustments, I'd wait a week and check the data — but there was never any meaningful improvement.

Mindset and the decision to pause

During this period, I was working a full-time job by day and doing Etsy at night. I invested a lot of energy, but the lack of progress — combined with directionless iteration and constant waiting for algorithmic changes — became exhausting.

I couldn't pinpoint the real problem: Was it the product? The listings? The exposure strategy? My understanding of the target user? That uncertainty pushed me toward burnout.

Eventually, I decided to pause — not to quit, but to give myself space to reflect and recover before moving forward.

You either succeed or you learn

Looking back, I've realized that action is everything. You can read, plan, and analyze forever — but nothing changes until you actually do something.

There's really no such thing as failure if you choose to see it as part of your growth. You either succeed, or you learn. This experiment turned out to be one of the most valuable things I did that year — which is why I wanted to write it down, partly for my future self, and partly for anyone who might stumble across it.

I'm reminded of something Charlie Munger said: if you want to avoid mistakes, you first have to know what mistakes look like. If you're thinking about starting an Etsy store, maybe this story can show you a few things not to do.

I still don't know exactly why mine didn't work out. But at least I tried — and that's the point. Because if you never take action, you'll never know what could have happened.

Originally written in 2023. Content may vary slightly across newer versions.

JavaScript's async story didn't start with async/await — it evolved through several patterns, each solving problems the previous one couldn't. This article traces that evolution from callbacks all the way to async functions.

Synchronous vs. asynchronous

JavaScript is single-threaded — code executes line by line within the call stack. Unless the previous task completes, the next one waits. This is simple to reason about, but if one task runs indefinitely, everything else is blocked and the browser appears frozen.

JavaScript's asynchronous paradigm addresses this. Instead of running in one go, an async task is split into stages with callbacks. HTTP requests are a classic example: once a request is sent, the response won't come back immediately, so a callback handles the result when it does.

Callbacks

The oldest solution. Given two functions f1 and f2 where f2 depends on f1's result:

f1()
f2()

If f1 takes a long time, refactor f2 as f1's callback:

function f1(callback) {
  setTimeout(function () {
    // f1's code
    callback()
  }, 2000)
}

f1(f2)

Pro: Simple to understand and implement. Con: As logic grows, callbacks become deeply nested, hard to read, and tightly coupled.

Event-driven programming

Tasks execute based on whether a specific event fires.

f1.on('done', f2)

function f1() {
  setTimeout(function () {
    // f1's code
    f1.trigger('done')
  }, 2000)
}

Pro: Easy to decouple; works well with modularisation. Con: The overall logic flow becomes harder to follow as the application grows.

Publish/Subscribe

Treat events as signals. A signal centre publishes when a task completes; other tasks subscribe to act on it — also known as the observer pattern.

Using Ben Alman's Tiny Pub/Sub:

jQuery.subscribe('done', f2)

function f1() {
  setTimeout(function () {
    // f1's code
    jQuery.publish('done')
  }, 2000)
}

jQuery.unsubscribe('done', f2)

Pro: Similar to event-driven, but the signal centre gives a clearer picture of what's happening across the application.

Promises

Proposed by CommonJS as a standardised async solution. Every async task returns a Promise with a then method:

f1().then(f2).then(f3)

Rewrite f1 with a deferred:

function f1() {
  var dfd = $.Deferred()
  setTimeout(function () {
    // f1's code
    dfd.resolve()
  }, 2000)
  return dfd.promise()
}

Handle errors:

f1().then(f2).fail(f3)

Pro: Callbacks are chained rather than nested. If a callback is attached after a task completes, it fires immediately — no risk of missing an event.

Generators

Introduced in ES6, generators can pause and resume execution using yield. They make async code read almost like synchronous code:

function* gen() {
  var url = 'https://api.github.com/users/github'
  var result = yield fetch(url)
  console.log(result.bio)
}

Executing it manually:

var g = gen()
var result = g.next()

result.value
  .then(function(data) { return data.json() })
  .then(function(data) { g.next(data) })

Generators also support two-way data flow and external error handling via .throw():

function* gen(x) {
  try {
    var y = yield x + 2
  } catch (e) {
    console.log(e)
  }
  return y
}

var g = gen(1)
g.next()
g.throw('error!') // error!

Con: The two-phase execution pattern can be confusing, and generators require an external executor (like the co library) to run automatically.

Async/Await

Introduced in ES7, async functions are syntactic sugar for generators — and considered the ultimate solution to async programming.

var asyncReadFile = async function () {
  var f1 = await readFile('/etc/fstab')
  var f2 = await readFile('/etc/shells')
  console.log(f1.toString())
  console.log(f2.toString())
}

Three improvements over generators:

1. Built-in executor — no co library needed; async functions run like regular functions.
2. Better semantics — async and await are self-explanatory compared to * and yield.
3. Better adaptability — await accepts both Promises and primitive values.

Async functions always return a Promise. Use try...catch for error handling:

async function main() {
  try {
    const val1 = await firstStep()
    const val2 = await secondStep(val1)
    const val3 = await thirdStep(val1, val2)
    console.log('Final: ', val3)
  } catch (err) {
    console.log(err)
  }
}

Run independent operations in parallel with Promise.all:

// slow — sequential
let foo = await getFoo()
let bar = await getBar()

// fast — parallel
let [foo, bar] = await Promise.all([getFoo(), getBar()])

Summary

References: Async JavaScript · Generator · Async

Originally written in 2024. Content may vary slightly across newer versions.

Introduction

In the world of Git, two techniques often take center stage: Merging and Rebasing. While both aim to combine changes from different branches, their methods and implications are vastly different. Understanding these approaches is crucial for managing your project’s history and navigating collaborative workflows effectively.

What is Merging in Git?

Merging is like having a big team of people (branches) with their own ideas, and when they all come together, they contribute their changes. The cool thing about merging is that everyone’s history stays intact. It’s like a potluck dinner where everyone brings their dish, and the new dish (the merge commit) gets added on top.

Example of Merging

Let’s say you have the following Git history:

A---B---C  (main)

 \

  D---E  (feature-branch)

When you merge feature-branch into main, Git creates a new merge commit (M). This happens because the branches have diverged, meaning they each have unique changes that need to be combined.

Git resolves this by finding the best common ancestor (BCA) — the most recent shared commit. In this case, A is the BCA, where both main and feature-branch started. Git then takes the changes from A → C (on main) and A → E (on feature-branch), and merges them into M.

The resulting history will look like this:

A---B---C---M  (main)

 \      /

  D---E  (feature-branch)

Notice how the merge commit ties everything together without altering the history of either branch. Now, the merge commit (M) has two parent commits, reflecting the branches that were merged.

When is a Merge Commit Not Needed? Fast-Forward Merges

If the branches haven’t diverged, Git doesn’t need a merge commit because it can simply “fast-forward” the main branch to include the commits from feature-branch.

In this case, the BCA will be the tip of the main branch.

Here’s the example:

A---B---C  (main)

          \
           D---E  (feature-branch)

In this scenario, C is the BCA because it’s the last commit shared by both branches. Since main has no new commits after C, Git can just “fast-forward” the main branch to include the changes from feature-branch (commits D and E).

The resulting history will look like this:

A---B---C---D---E  (main)

               (feature-branch)

It’s a clean and direct update.

Visualizing the Process

Want to see this all come together in a neat, visual way? Use the command:

git log --oneline --graph

Here’s the thing — — graph is a bit of an unsung hero in Git. This command provides a clear graph of your commit history, making it easy to spot merge commits, diverged branches, and how they come together. It’s simple and incredibly useful — give it a try!

What is Rebasing in Git?

Rebasing rewrites history, but what does that really mean?

It’s like taking a time machine to rearrange the sequence of events. Instead of having a merge commit that combines two branches, rebasing makes it appear as though your branch’s changes were always part of the target branch, created right after its latest commit.

When you rebase, Git moves your branch’s commits to the top of the target branch, giving you a straight, linear history. But this comes at a cost: the old history of your branch is replaced with a rewritten version.

How rebasing works: a three-step process

1. Start the rebase: Run the command:

git rebase <targetbranch>

For example, if your feature branch is currently checked out, running git rebase main will prepare Git to rebase feature-branch onto main.

1. Reapply commits one by one: Git checks out the latest commit on <targetbranch> (commit C on main), then takes each commit from <currentbranch> (D and E) and replays them on top of C, creating new commits D' and E'.

The original commits D and E are gone — their history has been replaced with rewritten versions. This is what "rewriting history" means: Git creates new versions of your commits that appear as if they were made after commit C.

1. Update the branch: Once all commits have been reapplied, Git updates <currentbranch> to point to the new commits:

A---B---C  (main)
             \
              D'---E'  (feature-branch)

feature-branch now has a clean, linear history that follows directly after main.

Golden rule: Only rebase private branches. For shared branches like main, always use merging to avoid rewriting history that others rely on.

Merging vs. rebasing: what's the difference?

Both merging and rebasing integrate changes from different branches, but in very different ways:

1. History: Merging keeps the history of both branches intact and creates a new commit that ties them together — like a time capsule. Rebasing rewrites history by replaying your commits on top of the target branch, making the timeline cleaner but changing how things appear to have happened.

2. Commit creation: Merging creates one new merge commit that combines everything. Rebasing creates multiple new commits — one for each of your original commits — each reapplied onto the target branch.

3. History shape: Merging produces a non-linear history with merge commits accumulating over time. Rebasing produces a straight, linear history with no merge commits.

When to use merging or rebasing?

Use merging if:

• You're working in a team and want a record of when branches were combined.
• You want a complete history that shows all merges.
• You want to avoid rewriting anything.

Use rebasing if:

• You prefer a clean, linear history with no merge commits.
• You're working solo or on a private feature branch.
• You're comfortable rewriting history on your own branch — but never on a branch others are already working with.

Merging vs. Rebasing: Independence vs. Adaptability

Here’s where things get interesting. I started thinking about these Git concepts from a personal perspective. Merging and rebasing aren’t just technical terms; they kind of reflect how we approach life, too.

Merging and Independence

Merging is like standing your ground. You’re your own person with your own history, and you’re just adding someone else’s history into your own without changing your past. It’s all about maintaining your independence while still being open to collaboration. You might take on someone else’s ideas, but you don’t change who you are.

Rebasing and Adaptability

Rebasing, on the other hand, is like being flexible and willing to adapt. It’s like saying, “Okay, I see what you did, and I’ll place my story in your timeline so that it makes sense.” It’s rewriting your own history to fit better with someone else’s. Rebasing is less independent because you’re conforming your story to someone else’s, but sometimes, that’s what we need to do in life to get things to work smoothly.

Conclusion

Merging and rebasing are both vital tools in your Git toolbox, but which one you use depends on the situation and your desired outcome. Merging is like keeping your own story intact while incorporating others, while rebasing is like rewriting your story to fit into another’s timeline. Both have their place in the world of version control (and life), so knowing when to use each will help you navigate your projects — and your personal development — with a bit more ease.

Development environment

• Xcode: 14.3.1
• macOS: Ventura 13.0.1
• React: 18.2.0
• React Native: 0.73.6
• react-native-vector-icons: 10.0.3

In this guide, italic text is quoted directly from the official documentation, and bold text is my own commentary.

Installation

npm install --save react-native-vector-icons

iOS setup

Open your iOS project in Xcode by navigating to your project directory and opening the .xcworkspace file.

Copy fonts to your Xcode project:

Navigate to node_modules/react-native-vector-icons and drag the Fonts folder (or specific fonts) into your Xcode project. Make sure your app is checked under "Add to targets," and if adding the whole folder, check "Create groups."

Your folder structure should look like this:

Edit Info.plist and add a property called Fonts provided by application (or UIAppFonts if Xcode autocomplete isn't working):

Full list of available fonts to copy into Info.plist:

<key>UIAppFonts</key>
<array>
  <string>AntDesign.ttf</string>
  <string>Entypo.ttf</string>
  <string>EvilIcons.ttf</string>
  <string>Feather.ttf</string>
  <string>FontAwesome.ttf</string>
  <string>FontAwesome5_Brands.ttf</string>
  <string>FontAwesome5_Regular.ttf</string>
  <string>FontAwesome5_Solid.ttf</string>
  <string>FontAwesome6_Brands.ttf</string>
  <string>FontAwesome6_Regular.ttf</string>
  <string>FontAwesome6_Solid.ttf</string>
  <string>Foundation.ttf</string>
  <string>Ionicons.ttf</string>
  <string>MaterialIcons.ttf</string>
  <string>MaterialCommunityIcons.ttf</string>
  <string>SimpleLineIcons.ttf</string>
  <string>Octicons.ttf</string>
  <string>Zocial.ttf</string>
  <string>Fontisto.ttf</string>
</array>

Check Build Phases:

In Xcode, select your project in the navigator, choose your app's target, go to the Build Phases tab, and under Copy Bundle Resources, add the copied fonts.

In some cases the fonts may already be listed under "Copy Bundle Resources" — if so, no action needed.

Create react-native.config.js:

When using auto-linking, all fonts are automatically added to Build Phases > Copy Pods Resources, which bloats your bundle. To prevent this, create a react-native.config.js file at the root of your project:

If the file doesn't exist yet, create it and set the iOS configuration to null.

module.exports = {
  dependencies: {
    'react-native-vector-icons': {
      platforms: {
        ios: null,
      },
    },
  },
};

Note: If you encounter a "Multiple commands produce…" error after following the official docs, remove any duplicate font references under "Copy Bundle Resources". See this issue thread for the fix with the most upvotes.

Rebuild your project — you're ready to use vector icons.

Android setup

Edit android/app/build.gradle (not android/build.gradle) and add:

apply from: file("../../node_modules/react-native-vector-icons/fonts.gradle")

Copy fonts to your Android project:

Navigate to android/app/src/main/assets/fonts and paste the Fonts folder there.

If the assets folder doesn't exist, create it — use lowercase for all folder names.

Originally written in 2024. Content may vary slightly across newer versions.

Integrating SVGs into React Native applications provides numerous benefits, allowing for dynamic styling and seamless handling of SVG files. This guide outlines two key approaches to harnessing the power of SVGs in React Native:

1. Utilizing Higher-Order Components (HOCs): HOCs serve as a powerful tool for enhancing the functionality of components in React Native applications. By implementing HOCs, developers can easily modify the color and size of SVG icons dynamically. This approach offers flexibility and reusability, enabling consistent styling across various components.

2. Leveraging react-native-transformer for SVG Handling: The react-native-transformer library facilitates the seamless integration of SVG files into React Native projects. It converts SVG XML text into React components that can be recognized and rendered by React Native, streamlining the management of SVG assets and ensuring compatibility with React Native's rendering engine.

SVG Transformation with React Native SVG Transformer

const { getDefaultConfig } = require("metro-config");

module.exports = (async () => {
  const {
    resolver: { sourceExts, assetExts },
  } = await getDefaultConfig();
  return {
    transformer: {
      babelTransformerPath: require.resolve("react-native-svg-transformer"),
    },
    resolver: {
      assetExts: assetExts.filter((ext) => ext !== "svg"),
      sourceExts: [...sourceExts, "svg"],
    },
  };
})();

This code configures Metro (the React Native bundler) to handle SVG files correctly. By default, Metro doesn't know how to process SVGs, so this configuration is necessary.

Here's what it does:

1. Calls getDefaultConfig() to obtain the default Metro configuration.
2. Retrieves the current resolver settings, including supported source and asset file extensions.
3. Adds .svg to the list of source file extensions so Metro can recognize and process SVG files.
4. Uses react-native-svg-transformer to convert SVG files into React components that can be imported directly.
5. Removes .svg from the asset file extensions list, since SVG files are now treated as source files instead.

Creating a Higher-Order Component (HOC) for SVGs

import React from "react";

import Colors from "theme/Colors";

export const withSvgIcon = (Component) => {
  const WithSvgIcon = ({ color = Colors.primary, width, height }) => {
    return (
      <>
        {width && height}
        ? (
        <Component style={{ color }} with={width} height={height} />
        ) : (
        <Component style={{ color }} />)
      </>
    );
  };

  return WithSvgIcon;
};

withSvgIcon is a higher-order component (HOC) that wraps an SVG component and exposes three props: color (defaults to Colors.primary), width, and height.

When width and height are provided, they are applied directly to the SVG. Otherwise, the component falls back to its default dimensions.

Dynamic Styling of SVGs

import React from "react";
import { withSvgIcon } from "./withSvgIcon";
import iconSvgContent from "./assets/icon.svg";

const IconComponent = withSvgIcon(iconSvgContent);

const App = () => {
  return (
    <View>
      <IconComponent color="red" width={20} height={20} />
    </View>
  );
};

export default App;

By combining these two approaches, SVG files are transformed into renderable React components with customizable color, width, and height props.

Recap

1. SVG icon import: Import SVG icons into the project.
2. Metro configuration: Set up react-native-svg-transformer to handle SVG files.
3. withSvgIcon HOC: Add dynamic styling capabilities to SVG components.
4. Usage: Use the styled SVG icons within your React Native components.

Troubleshooting

Why isn't the color prop changing my SVG icon's color?

Make sure the fill attribute in your SVG file is set to currentColor. Without this, the color prop has no effect — the SVG will render with its hardcoded fill instead of inheriting the color from the parent component.

Example:

In your SVG file, set fill="currentColor" on the path:

<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <path fill="currentColor" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"/>
</svg>

currentColor tells the SVG element to inherit the text color of its parent — which is how the color prop gets applied.

Still running into issues?

Check the react-native-svg-transformer documentation for dependency requirements and Metro configuration differences across React Native versions.

Don’t hesitate to drop a comment, hit that follow button for more React Native goodness! 🚀

Originally written in 2025. Content may vary slightly across newer versions.

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

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 tagsfield, 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 migrateruns, 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.

Originally written in 2025. Content may vary slightly across newer versions.

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

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.

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.

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.

Command Layer: Catch + Present

.command(
  'logout', 
  'Clear current user session', 
  {}, 
  async () => {
  try {
    // Business rule check
    const session = await requireUserSession(); 
    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 😊

Originally written in 2025. Content may vary slightly across newer versions.

A few weeks ago, something unexpected happened at work: my laptop stopped working properly, and IT told me the only option was to reinstall the system.

I use a Lenovo P1 running Windows 10 at work. In our company setup, all software is managed and installed through Software Center. Normally this works fine, but in my case, Software Center stopped working properly. That meant I couldn’t install any new software — which wasn’t an immediate blocker, but it was a problem waiting to happen.

For about two weeks, IT and I tried different ways to fix it. We went through the usual troubleshooting, but nothing worked. Even though the issue didn’t stop me from doing my daily work, I knew I couldn’t just ignore it. Sooner or later I’d need to install something new, and without Software Center, I’d be stuck. I had to deal with it once and for all.

At that point, the only options were to reinstall Windows or switch to a new laptop. Reinstalling would take too long, so I chose the second option: moving to a new machine. And that meant it was time to prepare a proper backup.

What I Decided to Back Up

When you’re about to switch laptops, it’s surprisingly hard to know what exactly you’ll need later. This was my first time really thinking it through, and I didn’t want to miss anything important. I broke it down into a few categories:

1. User files — Things in Desktop and Documents. These are easy to forget but also the simplest to copy.

2. Browser data — Mainly my Chrome bookmarks. I exported them as an .html file so I could import them later.

3. VS Code setup — I backed up the entire User folder, which included themes, fonts, and terminal configs.

4. Dev config — Just the essentials: my .gitconfig and SSH keys.

5. Email folders — In Outlook, I backed up a couple of emails I considered important, and some HR/Admin-related messages.

Restoring on the New System

Once I had the new laptop, I started putting everything back. Desktop and Documents were straightforward — I just copied them over, and everything ended up in the right place.

For Chrome, I opened the bookmarks manager and used Import Bookmarks to bring in the .html file I had exported. Everything was in the right folders, just like on my old laptop.

For VS Code, I first opened it once so that the User folder was created. Then I used the backup of my entire User folder to overwrite the new one. This restored all my settings. For extensions, I manually reinstalled them because of company restrictions.

For development configuration, I copied over .gitconfig and the .ssh folder, then tested my GitHub connection to make sure it worked.

For Outlook, I realized the backup wasn’t necessary — once I logged in, all my emails were already there.

Some of my project folders were large, so copying them took a few hours. In hindsight, since all the projects were already pushed to GitHub, I could have just cloned the repositories and set up the local environment, which would have been faster.

After finishing all of this, I checked over everything and realized the new laptop felt just like the old one. The whole restoration process was smoother and quicker than I had expected.

Lesson Learned

The main lesson I took away from this experience is that a little preparation goes a long way. Making sure I had all the core files backed up — like my user files, VS Code settings, and development configs — made the process smooth and predictable. Other things, like emails or project files that were already synced to the cloud, didn’t actually need to be backed up.

At first, I was worried about potentially losing something important and how that might affect my work. But once I went through the process, I realized that as long as I prepared properly, everything went smoothly. What initially felt like a stressful, high-stakes task turned into a manageable and controlled process.

Originally written in 2024. Content may vary slightly across newer versions.

Are you tired of your users getting redirected to external web browsers whenever they click on links within your React Native app? Say goodbye to this frustration with react-native-inappbrowser-reborn!

In this article, we’ll dive into the practical aspects of using react-native-inappbrowser-reborn to provide a seamless in-app browsing experience for your users.

By the end of this post, we’ll present a practical demo illustrating the integration of react-native-inappbrowser-reborn in a React Native app. What’s more, the code for this demo is readily usable in real projects — just copy and paste!

Introduction

react-native-inappbrowser-reborn is a powerful library that allows you to open external URLs within your React Native app’s interface, keeping users engaged without disrupting their experience. Whether you’re implementing authentication flows, payment gateways, or simply opening external links shared within the app, react-native-inappbrowser-reborn has got you covered.

Getting Started

Getting started with react-native-inappbrowser-reborn is a breeze. First, install the library in your React Native project:

npm install react-native-inappbrowser-reborn

Next, link the library to your native iOS projects:

cd ios && pod install && cd .. # CocoaPods on iOS needs this extra step

Opening URLs in In-App Browser

Let’s dive into the most exciting part — opening external URLs within your app using react-native-inappbrowser-reborn. Here’s a simple example demonstrating how to open a URL in the in-app browser:

import React from 'react';
import { TouchableOpacity, Text } from 'react-native';
import InAppBrowser from 'react-native-inappbrowser-reborn';

const ExternalLinkButton = ({ url }) => {
  const handleOpenLink = async () => {
    try {
      await InAppBrowser.open(url);
    } catch (error) {
      console.error('Failed to open link:', error);
    }
  };

  return (
    <TouchableOpacity onPress={handleOpenLink}>
      <Text>Open Link</Text>
    </TouchableOpacity>
  );
};

export default ExternalLinkButton;

Customization Options

react-native-inappbrowser-reborn provides various customization options to tailor the in-app browsing experience according to your app's needs. For example, you can specify additional options such as:

• Show/hide the browser’s title.

• Enable/disable navigation controls.

• Customize the browser’s presentation style.

Refer to the library’s documentation for a full list of available options and their usage.

Demo: Appointments and Messages Panels

Imagine you’re developing a mobile application for managing appointments and messages. You want to provide users with the ability to seamlessly access external content, such as messages from a messaging platform, without leaving the app’s interface. Let’s take a look at how this can be achieved using react-native-inappbrowser-reborn.

const handleContinueToMsgPortal = async url => {
  try {
    const isAvailable = await InAppBrowser.isAvailable();
    InAppBrowser.close();

    if (isAvailable) {
      return await InAppBrowser.open(url, {
        // iOS Properties
        modalPresentationStyle: 'formSheet',
        modalEnabled: true,
        enableBarCollapsing: false,
        // Android Properties
        showTitle: false,
        enableUrlBarHiding: false,
        enableDefaultShare: false,
        showInRecents: true,
      });
    }

    return await Linking.openURL(url);
  } catch (e) {
    Alert.alert(e.toString());
  }
};

This code snippet defines a function handleContinueToMsgPortal responsible for handling the redirection of users to an external messaging platform within a React Native app.

Here's a breakdown of its functionality:

1. Async Function: handleContinueToMsgPortal is an asynchronous function that takes a URL as its parameter. It's designed to handle asynchronous operations, such as checking for the availability of the in-app browser and opening the specified URL.

2. In-App Browser Availability Check: The function starts by checking if the in-app browser is available using InAppBrowser.isAvailable(). This method returns a boolean value indicating whether the in-app browser is available for use on the current platform.

3. Closing Existing Browser Instances: If the in-app browser is available, the function proceeds to close any existing browser instances using InAppBrowser.close(). This ensures that any previous browser sessions are terminated before opening a new one.

4. Opening the URL: If the in-app browser is available, the function attempts to open the specified URL using InAppBrowser.open(). It provides additional options for customizing the browser's behavior, such as setting modal presentation style on iOS and various properties on Android.

5. Fallback to Linking: If the in-app browser is not available or encounters an error during the opening process, the function falls back to using Linking.openURL() to open the URL in the device's default external browser.

6. Error Handling: The function includes a try-catch block to handle any errors that may occur during the process. If an error occurs, it displays an alert with the error message using Alert.alert().

Android demo

You may notice a behavioral difference between iOS and Android: While iOS utilizes the default browser and opens up the URL in a modal, Android opens up the URL in a custom tab from Chrome, occupying the entire space.

Alas, don’t forget to handle errors if anything goes wrong.

Conclusion

With react-native-inappbrowser-reborn, you can elevate your React Native app's user experience by seamlessly integrating in-app browsing capabilities. From opening external links to handling authentication flows, the possibilities are endless. Say goodbye to abrupt redirects to external browsers and hello to a cohesive app experience for your users.

The source code can be found on github. Happy coding! ☀️

Originally written in 2024. Content may vary slightly across newer versions.

Introduction

Swipe-to-delete functionality enhances user interaction by allowing effortless removal of items from lists with a simple swipe gesture. In this tutorial, we’ll demonstrate how to achieve swipe-to-delete in React Native projects, whether set up with React Native CLI or Expo!

Step-by-Step Guide: React Native CLI Project

Initialize a new React Native project using the React Native CLI:

npx react-native init SwipeToDeleteRN

Dependencies Installation:

Install the required dependencies for swipe-to-delete:

npm install react-native-gesture-handler

For iOS users, navigate to the iOS directory and run:

pod install

In the App.js, wrap the app within a gesture handler root view and ensure to apply flex: 1 to the component:

import { GestureHandlerRootView } from "react-native-gesture-handler";  
  
const App = () => {  
  return (  
    <GestureHandlerRootView style={{ flex: 1 }}>  
      <MessagesScreen />  
    </GestureHandlerRootView>  
  );  
};  
  
export default App;

The above code snippets contain a messages screen to display a list of messages that can be swipe deleted.

Here is the breakdown for the MessagesScreen component:

import { FlatList, StyleSheet } from 'react-native';
import React, { useState } from 'react';

import Screen from '../components/Screen';
import ListItem from '../components/ListItem';
import ListItemSeparator from '../components/ListItemSeparator';
import ListItemDeleteAction from '../components/ListItemDeleteAction';

const initialMessages = [
  {
    id: 1,
    title: 'title one',
    description: 'description one',
    image: require('../assets/cat.jpg'),
  },
  {
    id: 2,
    title: 'title two',
    description: 'description two',
    image: require('../assets/cat.jpg'),
  },
  {
    id: 3,
    title: 'title three',
    description: 'description three',
    image: require('../assets/cat.jpg'),
  },
];

export default function MessagesScreen() {
  const [messages, setMessages] = useState(initialMessages);
  const [refreshing, setRefreshing] = useState(false);
  const handleDelete = message => {
    setMessages(messages => messages.filter(item => item.id !== message.id));
  };
  return (
    <Screen>
      <FlatList
        data={messages}
        keyExtractor={item => item.id}
        renderItem={({ item }) => (
          <ListItem
            title={item.title}
            subTitle={item.description}
            image={item.image}
            onPress={() => console.log('item clicked.')}
            renderRightActions={() => (
              <ListItemDeleteAction onPress={() => handleDelete(item)} />
            )}
          />
        )}
        ItemSeparatorComponent={ListItemSeparator}
        refreshing={refreshing}
        onRefresh={() => {
          setMessages([
            {
              id: 1,
              title: 'title one',
              description: 'description one',
              image: require('../assets/cat.jpg'),
            },
          ]);
        }}
      />
    </Screen>
  );
}

const styles = StyleSheet.create({});

In this component:

• We define a state variable messages to hold the list of messages. Initially, it contains some dummy messages.

• We define a function handleDelete to remove a message from the list when the delete action is triggered.

• Inside the FlatList, each message is rendered using the ListItem component, which displays the title, description, and an image.

• The ListItemDeleteAction component is used to render the delete button, which triggers the handleDelete function when pressed.

• The renderRightActions prop of ListItem component renders the delete action using the ListItemDeleteAction component.

In the ListItem component, import Swipeable from react-native-gesture-handler/Swipeable and wrap it around the entire component while passing the renderRightActions prop:

import { Image, StyleSheet, TouchableHighlight, View } from 'react-native';
import React from 'react';
import Swipeable from 'react-native-gesture-handler/Swipeable';
import AppText from './AppText';
import Colors from '../themes/Colors';

export default function ListItem({
  title,
  subTitle,
  image,
  onPress,
  renderRightActions,
}) {
  return (
    <Swipeable renderRightActions={renderRightActions}>
      <TouchableHighlight underlayColor={Colors.lightGrey} onPress={onPress}>
        <View style={styles.container}>
          <Image source={image} style={styles.image} />
          <View style={styles.detailsContainer}>
            <AppText style={styles.title}>{title}</AppText>
            <AppText style={styles.subTitle}>{subTitle}</AppText>
          </View>
        </View>
      </TouchableHighlight>
    </Swipeable>
  );
}

const styles = StyleSheet.create({
  container: {
    flexDirection: 'row',
    padding: 15,
  },
  image: {
    borderRadius: 35,
    width: 70,
    height: 70,
    marginRight: 10,
  },
  detailsContainer: {
    justifyContent: 'center',
  },
  title: {
    textTransform: 'capitalize',
    fontWeight: '500',
    paddingVertical: 5,
  },
  subTitle: {
    fontSize: 16,
    color: Colors.mediumGrey,
  },
});

The renderRightActions prop should be a function that returns a React component (ie: ListItemDeleteAction) representing the delete UI.

import { StyleSheet, TouchableWithoutFeedback, View } from 'react-native';
import React from 'react';
import Colors from '../themes/Colors';
import Icon from 'react-native-vector-icons/AntDesign';

export default function ListItemDeleteAction({ onPress }) {
  return (
    <TouchableWithoutFeedback onPress={onPress}>
      <View style={styles.container}>
        <Icon name="delete" color={Colors.white} size={30} />
      </View>
    </TouchableWithoutFeedback>
  );
}

const styles = StyleSheet.create({
  container: {
    backgroundColor: Colors.dangerRed,
    width: 70,
    justifyContent: 'center',
    alignItems: 'center',
  },
  icon: {
    color: Colors.white,
  },
});

The source code can be found here on GitHub.

Step-by-Step Guide: Expo Project

Initialize a new Expo project:

expo init SwipeToDeleteExpo

Install Dependencies:

Add the required dependencies for swipe-to-delete:

expo install react-native-gesture-handler

Implement Swipe-to-Delete:

Follow the same steps as the React Native CLI project to implement swipe-to-delete using the Swipeable component. And DO NOT FORGET to import in your project’s entry file (e.g., App.js). Otherwise Swipeable won’t work!

Testing:

Run your Expo project using the Expo client app or on a physical device to test swipe-to-delete functionality.

Conclusion

By following the provided steps, you can seamlessly integrate swipe-to-delete functionality into your React Native projects, regardless of whether they are set up with React Native CLI or Expo. Enhance user experience and interaction by enabling users to efficiently manage lists with intuitive swipe gestures.

We encourage you to run the provided source code on your development environment. By doing so, you’ll gain a deeper understanding of how swipe-to-delete works in practice and how you can customize it to fit your specific project requirements.

Happy coding! ☀️

Originally written in 2024. Content may vary slightly across newer versions.

What is React Native, and how does it facilitate cross-platform development?

React Native enables developers to build mobile applications for both iOS and Android platforms using a single codebase.

Why is file management important in React Native development?

File management is crucial for many applications, such as handling downloads and opening files. Implementing these features requires consideration of platform-specific differences and permissions.

What tools or library should be used?

When it comes to file operations, the react-native-fetch-blob library offers robust capabilities. It provides a comprehensive set of functions for handling file downloads, uploads, and other file-related tasks in React Native applications.

File Download

Key considerations:

• Choose an appropriate directory based on the platform.

• Construct the file path using a unique identifier.

• Execute platform-specific download logic, handling permissions and errors accordingly.

import { PermissionAndroid, Platform, Alert } from "react-native";
import DeviceInfo from "react-native-device-info";
import ReactNativeBlobUtil from "react-native-blob-util";
import FileViewer from "react-native-file-viewer";
import _ from "lodash";

const downloadPdfToFileSystem = async (base64, fileId) => {
  const IS_IOS = Platform.OS === "ios";
  const {
    dirs: { DownloadDir, DocumentDir },
  } = ReactNativeBlobUtil.fs;
  const dirs = IS_IOS ? DocumentDir : DownloadDir;
  const path = dirs + '/' + fileId + '.pdf';

  try {
    if (!IS_IOS) {
      const systemVersion = DeviceInfo.getSystemVersion();
      const isDownloadAllowed = await PermissionAndroid.request(
        PermissionAndroid.PERMISSIONS.WRITE_EXTERNAL_STORAGE
      );

      if (
        systemVersion >= "11.0" ||
        isDownloadAllowed === PermissionAndroid.RESULTS.GRANTED
      ) {
        await ReactNativeBlobUtil.fs.writeFile(path, base64, "base64");
      }

      return path;
    }

    const ReactNativeBlobConfigs = { fileCache: true, path };
    const fileUrl = 'data:application/pdf;base64,' + base64;
    const response = await ReactNativeBlobUtil.config(
      ReactNativeBlobConfigs
    ).fetch("GET", fileUrl, {});

    return response.path();
  } catch (e) {
    console.log("PDF error ", e);
    Alert.alert(e.toString());
  }
};

To streamline file downloads, I’ve implemented a function called downloadPdfToFileSystem, which facilitates downloading PDF data in base64 format and storing it in the device’s file system.

Here’s a breakdown of the process:

1. Choose an appropriate directory based on the platform: Use DocumentDir for iOS and DownloadDir for Android.

2. Construct the file path using a unique identifier, fileId.

3. Execute platform-specific download logic:

For Android: Check the device’s system version. If it’s 11.0 or higher, no need to request WRITE_EXTERNAL_STORAGE permission; proceed with file writing. Otherwise, request permission using PermissionAndroid.request.

For iOS: Configure file cache and path using ReactNativeBlobUtil.config; Use the fetch method to retrieve the PDF file from base64 data and save it.

4. Handle errors gracefully: Log error messages to the console and display an alert dialog if any issues arise.

☀️ Highlights:

• Choice of Directories:

Documents directory in iOS and Downloads in Android: Selected based on platform differences, permission management, and user experience considerations.

Platform Differences: iOS and Android platforms have different file system structures. iOS apps typically save user-generated files in the Documents directory, while Android apps tend to save downloadable files in the external storage’s Downloads directory.

Permission Management: Accessing external storage on Android usually requires dynamically requesting permissions, especially after Android 11 (API level 30), which imposes stricter restrictions on file access. In contrast, iOS is relatively more lenient in terms of file access permissions and does not require explicit permission requests.

User Experience: Saving downloaded files in familiar locations can enhance user experience. For example, on Android devices, saving files to the Downloads directory allows users to easily locate downloaded files in the system file manager or other apps.

• Understanding PermissionAndroid.request

This function requests write access to external storage on Android. It’s an asynchronous operation, awaiting the user’s response, which can be granted, denied, or permanently denied (“never ask again”).

Based on the user’s response, developers can take appropriate actions, such as proceeding with the file writing operation or providing relevant prompts when the user denies the permission.

• Data URL Explanation

A data URL is a special format containing Base64-encoded data. In this case, it specifies the MIME type (“application/pdf”) and the encoded PDF content, guiding ReactNativeBlobUtil on data handling.

• Handling Image Downloads

For images, modify the MIME type to “image/jpeg” or “image/png” and replace “base64” with image data. This ensures proper handling by ReactNativeBlobUtil.

Check File Existence

const checkFileExistence = async (fileId) => {
  const IS_IOS = Platform.OS === "ios";
  const {
    dirs: { DownloadDir, DocumentDir },
  } = ReactNativeBlobUtil.fs;
  const dirs = IS_IOS ? DocumentDir : DownloadDir;
  const path = dirs + '/' + fileId + '.pdf';

  try {
    const isExist = await ReactNativeBlobUtil.fs.exists(path);
    return { isExist, path };
  } catch (e) {
    console.log("check file existence error ", e);
    Alert.alert(e.toString());
  }
};

This function checks the existence of a file by constructing the file path based on the provided fileId.

It uses the ReactNativeBlobUtil.fs.exists method to check if the file exists at the specified path. The result is stored in the isExist variable.

If any errors occur during the process, such as invalid file paths or permission issues, they are caught in thecatch block. The error message is logged to the console using console.logand displayed as an alert using Alert.alert.

Opening Downloaded Files

const openExistingFile = async (path, isInModalOrAlerts = false) => {
  const IS_IOS = Platform.OS === "ios";

  try {
    if (!IS_IOS) {
      return await ReactNativeBlobUtil.android.actionViewIntent(
        path,
        "application/pdf"
      );
    }

    // ReactNativeBlobUtil.ios.openDocument does not work with Modal and Alerts components
    // Reference: https://github.com/joltup/rn-fetch-blob/issues/243
    if (isInModalOrAlerts) {
      await FileViewer.open(path);
    } else {
      await ReactNativeBlobUtil.ios.previewDocument(path);
    }
  } catch (e) {
    console.log("open file error: ", e);
    Alert.alert(e.toString());
  }
};

On the Android platform, the ReactNativeBlobUtil.android.actionViewIntent method is employed to open the file. This method sends an action view intent, prompting the system to open the specified file.

On iOS, two different methods are used:

1. If the isInModalOrAlerts parameter is true, indicating that the current application context is within a modal dialog or alert, the FileViewer.open method is invoked to open the file. This is because the ReactNativeBlobUtil.ios.previewDocument method may not function properly within modal dialogs or alerts due to certain limitations.

2. If the isInModalOrAlerts parameter is false, indicating that the current application context is not within a modal dialog or alert, the ReactNativeBlobUtil.ios.previewDocument method is directly called to open the file.

In case of any errors, the error messages are logged using console.log and displayed using the Alert.alert method.

By following these guidelines, developers can simplify file download and viewing in React Native apps, ensuring smooth user experiences across iOS and Android platforms.

Originally written in 2024. Content may vary slightly across newer versions.

Managing timezone conversion is crucial in React Native development to ensure accurate time information for users across various timezones. This article addresses the common challenge faced by developers when dealing with timezone conversion and sorting, particularly in scenarios like appointment scheduling.

Project Requirement Scenario:

Imagine a React Native app with an appointment scheduling module. The app needs to display a list of upcoming appointments, each showing the date and time of the appointment. However, the appointment data is stored in different timezones and must be converted to the user’s timezone for accurate display. Additionally, appointments need to be sorted chronologically, irrespective of their original timezones.

Solution Overview:

To meet these requirements, we’ll implement timezone conversion and sorting functionality using several tools and libraries, including date-fns-tz, react-native-localize, and lodash. Our solution will be scoped to American timezones for simplicity.

Timezone Conversion Steps:

• Obtain date-time and timezone info: Retrieve original date-time and timezone data from appointments.

• Validate timezone: Ensure timezone is valid and within American timezones.

• Execute conversion: Use zonedTimeToUtc and utcToZonedTime to convert date-time from original to user’s local timezone.

• Handle errors: Gracefully manage any conversion errors, e.g., invalid timezones.

import { zonedTimeToUtc, utcToZonedTime } from 'date-fns-tz';
import { getTimeZone } from 'react-native-localize';

// Retrieve original date-time and timezone info from appointment data
const appointmentTime = '2023-02-20T08:00:00';
const appointmentTimeZone = 'America/New_York';

// Validate timezone information
const isValidTimeZone = isValidTimeZone(appointmentTimeZone);

if (isValidTimeZone) {
  try {
    // Get user's local timezone
    const userTimeZone = getTimeZone();

    // Execute timezone conversion
    const utcTime = zonedTimeToUtc(appointmentTime, appointmentTimeZone);
    const localTime = utcToZonedTime(utcTime, userTimeZone);

     // Retrieve timezone abbreviation for user's timezone
     const timeZoneAbbreviation = new Intl.DateTimeFormat('en-US', {
      timeZone: userTimeZone,
      timeZoneName: 'short'
    }).format(localTime).split(' ')[1]

    console.log('Converted appointment time:', localTime);
  } catch (error) {
    console.error('Error converting timezone:', error.message);
  }
} else {
  console.error('Invalid timezone:', appointmentTimeZone);
}

// Validate timezone is valid
function isValidTimeZone(timezone) {
  // Implement validation logic to ensure timezone is within valid range
  // Return true or false
}

Sorting Appointments:

• Employ lodash’s orderBy function to sort the appointments in descending order based on their date-time values.

import _ from 'lodash'

const sortedAppointments = _.orderBy(appointments, ['localTime'], ['desc'])

By following this approach, React Native developers can effectively handle timezone conversion and sorting in their projects, ensuring a seamless user experience across different timezones.

Feel free to share your experiences, thoughts, or challenges related to timezone handling in mobile apps in the comments section below.

😊 Fun Fact

In our appointment scheduling scenario, each appointment is stored using different timezones.

Interestingly, if the sorting is based solely on dates and doesn’t consider the time component, there’s no need for timezone conversion.

Dates, unlike times, are inherently timezone-agnostic. Regardless of your location, a specific date remains the same. Therefore, timezone conversion is only necessary when dealing with time-specific information. Since times can vary across different timezones, it’s crucial to handle timezone conversion appropriately to ensure accurate time representation in your React Native app.

Originally written in 2023. Content may vary slightly across newer versions.

This article is part of a series that document my first react native project. They encompass a variety of topics, and come in different shapes and flavours — some are hands-on notes, some are best practices (learn-and-think products by me), and some are an endeavour to get an in-depth understanding of the underlying mechanisms of how React / React Native works.

It is almost impossible not to use conditional rendering in a React / React Native app. Therefore, it is crucial for developers to understand the different scenarios in which conditional rendering is required and which kind of conditional rendering is most appropriate for the current situation.

The fundamentals — Part 1

Let's go over some fundamental knowledge about rendering in JSX. According to the React docs on JSX in depth, JSX expressions include Booleans, Null, and Undefined are ignored during rendering — they simply don't render.

Therefore, we are clear on the fact that if we want to conditionally render a component or for a component to skip rendering, we need to think about returning one of the above mentioned values instead.

The fundamentals — Part 2

There is a whole section dedicated to conditional rendering in the React docs, so I'd like to skip the reinventing-the-wheel play, and give you a few minutes to refresh your memory by quickly skimming through it.

I will go over each conditional rendering technique with a real-project-example and explains why a specific technique is suitable for the current situation.

Use Logical AND operator (&&)

Before jumping into the hands-on part, I’d like to say I'm very much inspired by Dana Janoskova in her article about how to write clean JSX and components. She talks about the approach to figure out which props are required and which are not. The basic idea is that you need to think about this question: what does this component do? And which props are necessary for the rendering of this component. In other words, without this prop / piece of data, the existence of this component is meaningless.

Equipped with this mindset, I set out to think about the purpose of the LocationItem component. This component is a modal that contains the detailed information about a certain location. When the user clicks on a LocationMarker component, this modal will show. So the most important part of this component or prop is the location prop.

In here, I want to use && operator because 1. isShowItem and !_isEmpty(location) both are required to be satisfied to render the LocationItem; 2. if both return true, then the LocationItem renders. If not, the expression returns false, which is also fine and renders nothing.

However, there is a pitfall you might want to pay attention to (because I did not so I’m writing this piece to remind myself not to repeat it). Avoid using empty strings or 0 in the conditions. Otherwise, it renders the empty strings or 0 !! And if you came across this, it throws an error: put text inside <Text />.

import React, { useState, useCallback } from 'react'
import _ from 'lodash'
import { Marker } from 'react-native-maps'

import LocationItem from 'Locations/LocationItem'
import styles from './styles'

const LocationMarker = ({ latitude, longitude, location }) => {
  const [isShowItem, setIsShowItem] = useState(false)
  
  const handleMarkerPress = useCallback(() => setIsShowItem(true))
  
  return (
    <Marker coordinate={{ latitude, longitude }} onPress={handleMarkerPress}>
    {isShowItem && !_.isEmpty(location) && (
      <LocationItem
        isShowItem={isShowItem}
        setIsShowItem={setIsShowItem}
        location={location}
      />
    )}
    </Marker>
  )
}

Use If to conditionally returning JSX

If this component needs to go into loading before rendering, it is more suitable to use if to conditionally returning JSX and avoid nesting at the same time (also inspired by Dana).

import React, { useState, useCallback } from 'react'
import _ from 'lodash'
import { Marker } from 'react-native-maps'

import LocationItem from 'Locations/LocationItem'
import styles from './styles'

const LocationMarker = ({ latitude, longitude, location }) => {
  const [isShowItem, setIsShowItem] = useState(false)
  
  const handleMarkerPress = useCallback(() => setIsShowItem(true))
  
  if (!longitude || !latitude) {
    return null
  }
  
  return (
    <Marker coordinate={{ latitude, longitude }} onPress={handleMarkerPress}>
    {isShowItem && !_.isEmpty(location) && (
      <LocationItem
        isShowItem={isShowItem}
        setIsShowItem={setIsShowItem}
        location={location}
      />
    )}
    </Marker>
  )
}

Using the same example as before, I only added the if condition for longitude & latitude. This component only needs to render if it has valid longitude and latitude values.

To sum up, conditional rendering is a must if you are developing using React or React Native. Hope a few tips can help you a long way!

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.

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.

https://twitter.com/czhoudev/status/1890735259190440170

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!

https://www.youtube.com/watch?v=M74mX-gAlKo

💬 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! 🚀

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!

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.

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 love to hear what tripped you up too — drop it in the comments.

🛠 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