
### Understanding the Hidden Pitfalls of Custom Hooks in React

In a previous post we covered [How React Rerenders Works](/blog/react-rerender). But today, we'll take a closer look at
the hidden pitfalls of custom hooks in React.

<Image alt="Hand-drawn diagram showing 'Custom React Hooks' as the main title with small hook illustrations, 'useEffect ( )' written in blue text on the left, and the React logo (atomic symbol) in blue on the bottom right." src="hooks.jpg" priority={true} />

When we handle state, component re-renders, and application performance in React, custom hooks are a powerful tool that
help us keep our components clean and manageable. However, this simplicity can sometimes hide performance issues that we
may not immediately notice.

Consider a basic custom hook for toggling the visibility of a tooltip:

```jsx
const useTooltipToggle = () => {
  const [visible, setVisible] = useState(false);

  return {
    visible,
    show: () => setVisible(true),
    hide: () => setVisible(false),
  };
};
```

Using this hook in a component might look neat and clean:

```jsx
const App = () => {
  const {
    visible,
    show,
    hide
  } = useTooltipToggle();

  return (
    <div className="app-container">
      <button onMouseEnter={show} onMouseLeave={hide}>Hover me!</button>
      {visible && <Tooltip text="Hello, Tooltip!" />}
      <HeavyComputationComponent />
      <AnotherIntensiveComponent />
    </div>
  );
};
```

At first glance, this setup appears elegant—state logic neatly wrapped in the `useTooltipToggle` hook. However, this
approach hides a subtle performance issue: whenever the tooltip visibility state changes, React re-renders the entire
`App` component, despite the state being limited to a small interaction.

> Why? You can read more about react rerenders [here](/blog/react-rerender).

### Hidden States and Re-rendering Pitfalls

Let's extend our custom hook to listen for a scroll event:

```jsx
const useTooltipToggle = () => {
  const [scrollPosition, setScrollPosition] = useState(window.scrollY);

  useEffect(() => {
    const handleScroll = () => setScrollPosition(window.scrollY);
    window.addEventListener('scroll', handleScroll);

    return () => window.removeEventListener('scroll', handleScroll);
  }, []);

  return {
    // For example, this part of the code was simplified
    visible: false,
    show: () => {},
    hide: () => {},
  };
};
```

Now, every time the user scrolls, this hook updates the state internally. Even though the scrolling position isn't
returned or directly used, it **triggers state changes**, causing the entire `App` to re-render unnecessarily.

### Nested Hooks Can Multiply Issues

The problem worsens when custom hooks depend on other hooks indirectly. For example, consider another hook for tracking
mouse movement:

```jsx
const useMouseTracker = () => {
  const [mousePosition, setMousePosition] = useState({
    x: 0,
    y: 0
  });

  useEffect(() => {
    const updateMousePosition = (e) => setMousePosition({
      x: e.clientX,
      y: e.clientY
    });
    window.addEventListener('mousemove', updateMousePosition);

    return () => window.removeEventListener('mousemove', updateMousePosition);
  }, []);

  return null;
};

const useTooltipToggle = () => {
  useMouseTracker();

  return {
    // For example, this part of the code was simplified
    visible: false,
    show: () => {},
    hide: () => {},
  };
};
```

Even if `useTooltipToggle` does not directly use mouse position state, the `App` component still re-renders each time
the mouse moves, since the state is updated inside the nested hook.

> Hiding stateful logic within hooks doesn't remove their performance impact. The
> solution isn’t hiding complexity but smartly managing and isolating the state.

### How to Solve This

To avoid such issues, encapsulate state logic in smaller components:

```jsx
const Tooltip = () => {
  const {
    visible,
    show,
    hide
  } = useTooltipToggle();

  return (
    <>
      <button onMouseEnter={show} onMouseLeave={hide}>Hover me!</button>
      {visible && <Tooltip text="Hello, Tooltip!" />}
    </>
  );
};
```

This ensures that the minimal required area re-renders, preventing unnecessary updates across the entire app.

> In this solution, the `Tooltip` logic moved down from `App` to the own component. I described this approach in
> [this article](/blog/react-rerender#moving-state-down).

### Key Takeaway

The key lesson: carefully handle state encapsulation within custom hooks. Keep state management local and focused to
optimize your React application's performance and responsiveness.

> P.S Memoization and other performance optimizations will be covered in future posts.


Learn about the subtle performance risks hidden in React custom hooks, how they can cause unexpected re-renders, and strategies to manage state efficiently.

Understanding the Hidden Pitfalls of Custom Hooks in React


<Image alt="" src="react-rerender.png" priority={true} />

Hi, react [Andy](https://en.wiktionary.org/wiki/react_Andy)!

I’ve used React for over six years. I’ve noticed that even skilled programmers often struggle to grasp how React
operates behind the scenes. This can lead to inefficiencies. It affects code quality, speed, and user experience.

The documentation is great for starting with React. Many [books](https://www.roadtoreact.com/), courses, and blogs focus
on beginners. But what comes next? How can you dive deeper and really understand how it works? If you’ve been writing
React for a while, basic or
even intermediate courses may not be enough. Sadly, resources for advanced learning are limited.

That’s why I’m launching a [series of articles](/blog/category/advanced-react) to fill this knowledge gap.

## Intro to re-renders

Understanding re-renders in React is crucial for performance. You need to understand what triggers them. Know how they
move through the app. Learn what happens during a re-render and why it matters.

<Image alt="" src="react-meme.png" />

## The problem

Imagine you’re an intern at a FAANG company. Your first task is to create a new React component. You’re asked to add a
simple `button` that opens a `modal dialog` at the top of the app.

```jsx
const App = () => {
  // Some code here
  return <div className="layout">
    {/* The button should go somewhere here */}
    <VerySlowComponent />
    <AnotherComponent />
    <OtherStuff />
  </div>;
};
```

Then you implement it. The task seems trivial. We've all done it hundreds of times:

```jsx
const App = () => {
  // Add state  
  const [isOpen, setIsOpen] = useState(false);

  // Everything that is returned here will be re-rendered when the state is updated
  return <div>
    {/* Add the button */}
    <Button onClick={() => setIsOpen(true)}>
      Open dialog
    </Button>

    {/* Add the dialog */}
    {isOpen && <ModalDialog onClose={() => setIsOpen(false)} />}

    <VerySlowComponent />
    <AnotherComponent />
    <OtherStuff />
  </div>;
};
```

You add [state](https://react.dev/learn/state-a-components-memory) to track if the dialog is open or closed. You include
a button to change the state and render the dialog
based on this state.

When you run the app, there’s a noticeable delay ⏰, **almost a second** — before the dialog appears.

Experienced React developers might quickly suggest.

> "You’re re-rendering the whole app. Just wrap everything in [React.memo](https://react.dev/reference/react/memo) and
> use [useCallback](https://react.dev/reference/react/useCallback) to avoid unnecessary renders."

This advice has its place, but it’s wise to pause before jumping in. In this case, memoization isn’t needed and could
hurt performance.

First, let’s take a closer look at what exactly is happening and why this delay occurs.

<Image alt="" src="rerender.png" />

When we click the button, we trigger the `setIsOpen` setter function, which updates the `isOpen` state from `false` to
`true`. As a result, the `App` component that holds this state re-renders itself.

After the state updates and the `App` component re-renders, React must pass the new data to other dependent components.
It automatically re-renders all components that the first component shows. It keeps going down the tree until it reaches
the end.

If you visualize a typical React app as a tree structure, you will find that everything beneath the point where the
state update was initiated will be re-rendered.

> Re-rendering is crucial to understand in React.

The key point to remember is that React never re-renders components "up" the render tree. If a state update occurs in
the middle of the component tree, only the components "down" the tree will be re-rendered.

<Image alt="" src="rerender-state.png" />

When a component is wrapped in `React.memo`, `React` will interrupt its default re-rendering process and first evaluate
whether the `props` have changed. If there are no changes to the `props`, re-renders will be halted. However, if even a
single `prop` is modified, the re-rendering will proceed as usual.

It's important to note that effectively preventing re-renders through memoization is a nuanced topic with various
considerations. For a deeper understanding, it is advisable to explore these concepts further in new articles. (Comming
soon...)

<Image alt="" src="react-memo.png" />


Wrapping components with `React.memo` can indeed help prevent unnecessary re-renders in certain scenarios. However, it's
important to note that using `React.memo` comes with its own set of complexities and caveats, which will be discussed in
future articles. A more effective approach is to isolate the components that rely on specific state and encapsulate both
the state and those components into a smaller, dedicated component. This can lead to improved performance and a clearer
component structure.

## Moving state down

Let's move our logic in separated component.

```jsx
const ButtonWithModalDialog = () => {
  const [isOpen, setIsOpen] = useState(false);

  return <>
    <Button onClick={() => setIsOpen(true)}>
      Open dialog
    </Button>

    {isOpen && <ModalDialog onClose={() => setIsOpen(false)} />}
  </>;
};
```

And then render this new component in the `App`:

```jsx
const App = () => {
  return <div>
    // Our new component
    <ButtonWithModalDialog />

    <VerySlowComponent />
    <AnotherComponent />
    <OtherStuffComponent />
  </div>;
};
```

<Image alt="" src="rerender-performance-fix.png" />

Consequently, the modal dialog appears immediately. We resolved a significant performance issue using a straightforward
composition technique!


Dive into the mechanics of React re-renders — learn what causes them, how they impact performance, and how to manage them effectively.

Understanding React Re-Renders: What Triggers Them and Why They Matter


<Image alt="A hand-drawn diagram showing Generic Type Parameters on the left and a browser window with TypeScript code for a generic identity function on the right, plus two boxes labeled U and V" src="generic.jpg" priority={true} />

When you first encounter TypeScript generics, you'll likely see something
like [this](https://www.typescriptlang.org/docs/handbook/2/generics.html#hello-world-of-generics):

```typescript
function identity<T>(arg: T): T {
  return arg;
}
```

That lonely **T** sitting there might seem mysterious.

Why T? What if you need more than one? And when should you graduate from single letters to something more descriptive?
Let's dive into the world of generic naming conventions and figure out what actually makes sense.

## The Classic Lineup: T, U, V, W

The **T** convention comes from mathematics and early programming languages. It simply stands for "Type" – nothing
fancy.
When you need multiple generic parameters, the tradition is to march through the alphabet:

```typescript
// Two types? Add U
function pair<T, U>(first: T, second: U): [T, U] {
  return [first, second];
}

// Three types? Bring in V
function triple<T, U, V>(first: T, second: U, third: V): [T, U, V] {
  return [first, second, third];
}
```

This alphabetical progression isn't arbitrary – it creates a clear, predictable pattern that developers can follow
easily. Plus, these single letters are visually distinct and don't clutter your code.

> This naming convention is common in different languages,
> like [Java](https://docs.oracle.com/javase/tutorial/java/generics/types.html) and others.

## When Single Letters Work Perfectly

For simple, general-purpose functions and utilities, single letters are your best friend:

```typescript
// Array mapping - crystal clear what T and U represent
function map<T, U>(items: T[], transform: (item: T) => U): U[] {
  return items.map(transform);
}

// Key-value pairs - K and V are intuitive
interface Dictionary<K, V> {
  [key: K]: V;
}
```

> Notice how TypeScript's own built-in utilities follow this pattern. `Pick<T, K>`, `Omit<T, K>`, `Record<K, V>` – they
> stick with meaningful single letters because the context makes their purpose obvious.

## The Case for Descriptive Names

Sometimes, though, single letters leave your future self (and your teammates) scratching their heads. That's when
descriptive names shine:

```typescript
// What are T and U supposed to represent here?
interface ApiClient<T, U> {
  get(endpoint: string): Promise<T>;
  handleError(error: U): void;
}

// Much clearer!
interface ApiClient<ResponseData, ErrorType> {
  get(endpoint: string): Promise<ResponseData>;
  handleError(error: ErrorType): void;
}
```

This is especially valuable in domain - specific code where the generic types have special meaning in your business logic.

## The Repository Pattern Example

Here's where descriptive naming really pays off:

```typescript

interface Repository<Entity, Key> {
  findById(id: Key): Promise<Entity | null>;
  save(entity: Entity): Promise<Key>;
  delete(id: Key): Promise<void>;
  findAll(): Promise<Entity[]>;
}


class UserRepository implements Repository<User, string> {
  // Implementation details...
}
```

Anyone reading this code immediately understands what **Entity** and **Key** represent.
Compare that to `Repository<T, U>` – you'd need to dig into the implementation to figure out which is which.

## The T Prefix Debate

You'll sometimes see generic parameters prefixed with T:

```typescript
interface Repository<TEntity, TKey> {
  findById(id: TKey): Promise<TEntity>;
}
```

This convention comes from [C#](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic?view=net-9.0) and serves a purpose – it clearly marks something as a **type parameter** rather than a
**regular variable**. But it's not universally loved.

TypeScript's own standard library doesn't use the T prefix.
React components rarely use it. Many JavaScript and TypeScript projects skip it entirely:

```typescript
// Both are perfectly valid
interface Props<User, Settings> {}
interface Props<TUser, TSettings> {}
```

The choice often comes down to team preference and consistency with your existing codebase. Pick one style and stick
with it.

## Practical Guidelines

Here's what I've learned from years of writing TypeScript:

### Use single letters when:

- Writing utility functions that work with any type 
- The generic's role is obvious from context 
- You're following established patterns (like `map<T, U>`)

### Use descriptive names when:

- The generics have a specific domain meaning 
- You have multiple related type parameters 
- Code clarity would suffer with single letters

### Stay consistent:

- Whatever convention your team chooses, apply it everywhere 
- Don't mix T prefixes with non-prefixed names randomly 
- Document your team's preferred style

## Common Single-Letter Conventions

```typescript
T // Primary type parameter
U, V, W // Additional type parameters (alphabetical order)
K // Key type (in mappings, records)
V // Value type (in key-value structures)
E // Element type (in collections)
R // Return type
P // Properties/Props type
```

## Wrapping Up

- **Consistency beats perfection** – pick a style and stick with it 
- **Context is king – choose names** that make sense for your specific use case 
- **When in doubt, be descriptive** – clarity trumps brevity in complex code 
- **Follow your team's conventions** – consistency across the codebase matters most

> I love conventions and wrote a lot of articles about them.
> Check out about [conventional commits](/blog/conventional-commits) and [JavaScript Naming](/blog/javascript-naming-conventions) for more.


Understanding Generics Parameters naming conventions.

What is a generic type parameter T in TypeScript?


If you’re interested in GraphQL but haven’t had the chance to explore it directly, it's time to take action.
[Apollo Odyssey](https://www.apollographql.com/tutorials/) is the perfect solution to help you understand how it all
fits together!

<Image alt="Apollo Graph Developer - Associate certificate. Serhii Shramko" src="graphql-certificate.png" priority={true} />

## Apollo Odyssey: Free Learning Platform

The learning platform features a variety of paths, combining video tutorials with written guides that include quizzes
and code challenges for reinforcement.

<Image alt="Apollo Odyssey: Learning Platform video" src="graphql-apollo-odyssey.png" />


To earn
the [Apollo Graph Developer - Associate certification](https://www.apollographql.com/tutorials/certifications/apollo-graph-associate),
you must complete the first four paths:

- [Basics](https://www.apollographql.com/tutorials/lift-off-part1)
- [Resolvers](https://www.apollographql.com/tutorials/lift-off-part2)
- [Arguments](https://www.apollographql.com/tutorials/lift-off-part3)
- [Mutations](https://www.apollographql.com/tutorials/lift-off-part4)

> Developers who obtain this certification possess a solid foundational knowledge of GraphQL and the Apollo tool suite
> to design a schema, run an Apollo Server 4, and perform queries with Apollo Client 3 on the frontend.

I absolutely love this platform! It features fantastic videos, clear explanations, and some really good jokes that
always make me smile. 😀

## Apollo Graph Developer - Associate

As you work your way through the four required tutorials, you will be creating a real-world application called
`Catstronauts`.

<Image alt="Catstronauts project. React & GraphQL application" src="catstronauts.png" />

This project consists of a frontend client built with _TypeScript_ and _React_, alongside a backend server that utilizes
_Node.js_ as its runtime environment and [Apollo Server](https://www.apollographql.com/docs/apollo-server) as a
standalone, spec-compliant GraphQL server.

## Certification exam

- 31 multiple choice questions
- 25 correct answers required to pass

I achieved success in my test, making only a single error.

This outcome highlights the effectiveness of the course, which comprehensively addresses all relevant material,
equipping me with the confidence to approach the exam calmly.

## Graph Developer - Professional

Well, now the next step is to gain a deeper knowledge of GraphQL and
get [Graph Developer - Professional](https://www.apollographql.com/tutorials/certifications/apollo-graph-professional)
certification.

> Developers who obtain this certification demonstrate strong familiarity with Apollo Federation concepts. They can
> apply those concepts to build a federated supergraph or move an existing monolithic graph to federation.

I really commend the [Raphael Terrier](https://www.linkedin.com/in/raphaelterrier/)
and [Michelle Mabuyo](https://www.linkedin.com/in/michellemabuyo/) for developing such an excellent learning course.


Astro is a new Javascript framework, so discover what makes it special and what are its core features.

How I Got Apollo GraphQL Certification for Free


<Image src="linktree.jpeg" alt="My linktree" priority />

**1 hour** of work and I have my own link tree website with Astro.js and Vercel on my own subdomain.

Check out the final result: [links.shramko.dev](https://links.shramko.dev/)

## Why Astro.js?

I [wrote about Astro.js](/blog/astro), and I was impressed by its performance and ease of use.
<abbr title='In my humble opinion'>IMHO</abbr>, Astro one of the most promising and fast-growing static site generators out there.

<Image src="astro-chart.jpg" alt="Astro Framework chart on State of JS" />

### Speed and Performance

Try to check my website on [PageSpeed Insights](https://pagespeed.web.dev/analysis/https-links-shramko-dev/uemqqap32n?form_factor=mobile) and you will see that it is fast and efficient.

<Image src="lighthouse.png" alt="My webstite metrics on Google lighthouse" />


## Setting Up the Project

I started by creating a new Astro project:

```bash
pnpm create astro@latest
```

You can read small article about why I use [pnpm](/blog/pnpm) 🤘.

## Data for the Link Tree

First of all I created a data file with my links. I used a simple JSON structure:

```json:data/user.json
{
  "name": "Serhii Shramko",
  "profession": "Senior Software Engineer",
  "links": [
    {
      "url": "https://shramko.dev/",
      "icon": "url",
      "title": "Personal Portfolio",
      "description": "All my latest news and blog posts"
    },
    {
      "url": "https://github.com/Shramkoweb",
      "icon": "github",
      "title": "Github Profile",
      "description": "My Github"
    }
  ]
}
```

This approach allows me to easily add, remove, or update links without changing the HTML structure.

## Layout and File Structure

Astro.js allow use simple file structure. And for this project I don't need complex structure. I created an index page:

```jsx:pages/index.astro
---
import Layout from '../layouts/Layout.astro';
import Profile from '../components/Profile.astro';
import List from '../components/List.astro';
// Simple component that renders the main layout, the profile, and the list of links.
---

<Layout title="Link tree | Serhii Shramko">
    <main class="container" id="container">
        <Profile />
        <List />
    </main>
</Layout>
```

```jsx:components/Link.astro
---
import Instagram from "./icons/instagram.astro";
import Linkedin from "./icons/linkedin.astro";
import Url from "./icons/url.astro";
import Youtube from "./icons/youtube.astro";
import Pdf from "./icons/pdf.astro";
import Github from "./icons/github.astro";

interface Props {
    icon: string;
    title: string;
    description: string;
    url: string;
}

const { icon, title, description, url } = Astro.props;
---

<a href={url} class="link" target="_blank">
    <span class="link__icon">
        {icon === 'instagram' && <Instagram />}
        {icon === 'linkedin' && <Linkedin />}
        {icon === 'url' && <Url />}
        {icon === 'youtube' && <Youtube />}
        {icon === 'github' && <Github />}
        {icon === 'pdf' && <Pdf />}
    </span>

    <div class="link__content">
        <h2 class="link__title">{title}</h2>
        <p class="link__description">{description}</p>
    </div>
</a>
```

Astro.js allows you to create components from svg code. I created a separate component for each icon:

```jsx:components/icons/github.astro
<svg xmlns="http://www.w3.org/2000/svg" width="800" height="800" viewBox="0 0 20 20"></svg>
```

## Analytics

Almost done. Just add Vercel Analytics to the project.

<Image src="astro-analytics.jpg" alt="Analytics on vercel" />

```bash
pnpm add @astrojs/vercel
pnpm add @vercel/analytics
```

```js:astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

// https://astro.build/config
export default defineConfig({
    output: 'server',
    adapter: vercel({
        webAnalytics: { enabled: true }
    }),
});
```

## Deploying to Vercel

[Vercel makes deploying](https://vercel.com/docs/frameworks/astro) Astro projects a breeze. Here's how I did it:

1. I pushed my project to a GitHub repository.
2. I connected my Vercel account to my GitHub account.
3. In the Vercel dashboard, I clicked "New Project" and selected my link tree repository.
4. Vercel automatically detected that it was an Astro project and suggested the correct build settings.
5. I clicked "Deploy" and waited for the magic to happen!

## Custom Domain with Vercel Subdomains

<Image src="vercel-domain.jpg" alt="Domain on vercel" />


To use my custom domain with Vercel, I followed these steps:

1. In the Vercel project settings, I navigated to the "Domains" section.
2. I added my custom domain: `links.shramko.dev`.
3. Done! Vercel automatically set up the necessary DNS records for me.

## Conclusion

Building a link tree with Astro.js and deploying it on Vercel was a smooth and enjoyable process. I spent no more than
an hour and got a fast, efficient, and visually appealing website that and try new technologies.

Sounds great, right? 🌲


Learn how to build a fast, efficient link tree website using Astro.js, deploy it with Vercel, set up a custom subdomain, and implement Vercel Analytics for performance insights.

Building a Link Tree with Astro.js and Vercel: A Step-by-Step Guide

<Image src="git.jpg" alt="Hand-drawn illustration of the Git logo inside a tilted square outline with three red dots connected by black lines, representing branches" priority={true} />

When it comes to managing version control in your project with Git, `.gitignore` files typically handle most cases of
excluding specific files or directories from being tracked. However, there are instances when you either can’t or simply
prefer not to modify the `.gitignore` file directly.

Fortunately, Git offers several alternative methods to tackle these scenarios effectively.

### Why You Might Want to Avoid Modifying .gitignore

There are generally two key situations where you might opt to keep your `.gitignore` unchanged:

1. **Personal or local-specific files:** Say you have custom settings or environment files (like `.envrc` or
   personalized
   IDE configurations). You wouldn’t want to clutter the repository with your personal preferences that aren’t relevant
   to others.
2. **Temporarily ignoring changes to tracked files:** Perhaps you’re making adjustments to a file that’s already under
   version control (such as a Docker configuration or database settings), but you want to ensure these changes don’t
   appear in every commit.

Here’s how to handle both situations gracefully.

### Ignoring untracked files

Git provides a straightforward solution that keeps personal preferences out of sight from collaborators: the
`.git/info/exclude` file. This file acts just like `.gitignore` but remains local—meaning your teammates won’t be
affected
by your individual exclusions.

To put this into action, simply open the `.git/info/exclude` file in your repository and list the files or directories
you
wish to ignore:

```gitignore
.idea/
*.log
.env.local
```

Now, your IDE settings, log files, or local environment configurations will no longer clutter your Git status or lead to
accidental commits without interrupting your teammates’ workflow.

### Temporarily Ignoring Changes with git update-index

At some point, you’ll find it necessary to tweak files you’re already tracking, but you have no intention of committing
those changes (for example, adjusting local ports or temporary debugging code). That’s where the
`git update-index --assume-unchanged` command comes in.

Here’s how it works:

To temporarily ignore changes in a tracked file, simply run:

```bash
git update-index --assume-unchanged docker-compose.yml
```

This command tells Git to overlook any further changes made to `docker-compose.yml`, treating it as if it hasn’t been
modified.

However, use this feature with caution! Overuse can lead to confusion, especially if you forget you’ve set it. To resume
tracking the changes, you can run:

```bash
git update-index --no-assume-unchanged docker-compose.yml
```

If you ever need a quick way to check which files are being ignored, you can use:

```bash
git ls-files -v | grep '^h'
```

This command lists the files that Git currently assumes are unchanged, helping you maintain organization.

### Final Thoughts

While `.gitignore` is a powerful tool, it’s not always enough on its own. By incorporating `.git/info/exclude` and the
`git update-index` technique into your toolkit, you can enjoy greater flexibility in managing your repository.

Precise management leads to fewer headaches and cleaner commits, ensuring a smoother and more intuitive approach to
version control.


Learn about Git's hidden alternatives to .gitignore for managing file exclusions locally without affecting your team's workflow.

When .gitignore Isn't the Right Tool


Let’s talk about version numbers in your `package.json`. You’ve probably seen versions like `1.2.3` or `^4.5.0`—but what
do they *actually* mean?

<Image src="semver.jpg" alt="but it works on *my* machine  joke" />

---

## **SemVer: The Three-Number System That Keeps Everyone Sane**

Semantic Versioning (SemVer) is just a fancy way of saying:  
**“Hey, let’s use version numbers to tell people what *kind* of changes we made.”**

Versions look like `x.y.z`:

- **Major (x)**: Big changes that might break your code. *Example:* Removing a feature your app relies on.
- **Minor (y)**: New stuff that won’t wreck existing code. *Example:* Adding a cool new function.
- **Patch (z)**: Quiet fixes for bugs or security holes. *Example:* Fixing a crash when you type `null`.

Think of it like home renovations:

- **Major** = Tearing down a wall (big impact).
- **Minor** = Adding a new room (no harm done).
- **Patch** = Fixing a leaky faucet (everyone’s happy).

---

## **Why Should You Care?**

Because npm uses these numbers to decide which updates are safe to install automatically. If everyone follows SemVer,
your app won’t suddenly break when you run `npm update`.

---

## **The Secret Symbols in Your package.json**

Those weird characters like `^` and `~` in your dependencies? They’re just rules for npm. Here’s what they *really*
mean:

- **`^1.2.3`** = “New features and fixes are okay, but don’t change anything big!”  
  *(Updates to 1.3.0 or 1.2.4 are fine. Won’t jump to 2.0.0.)*

- **`~1.2.3`** = “Only tiny fixes, please.”  
  *(Updates to 1.2.4 are okay. Won’t go to 1.3.0.)*

- **`>` or `>=`** = “Give me anything newer than this.”
- **`<` or `<=`** = “Nothing newer than this, thanks.”
- **`1.2.3` - `1.5.0`** = “I’ll take any version between these two.”
- **`||`** = “Either version A *or* version B works.”

**No symbol?** Example: `"lodash": "4.17.21"` means *“Only this exact version. Don’t change a thing!”*

---

## **Real-World Tips for Humans**

1. **Start with `^`** for most dependencies. It’s the safest way to get bug fixes and new features without surprises.
2. **Use exact versions** for critical packages (like React or Vue) where unexpected changes could ruin your day.
3. **Check `npm outdated` weekly** to see which packages have updates. It’s like a to-do list for your app’s health.
4. **Commit `package-lock.json`** to avoid “but it works on *my* machine” moments. This file locks down every tiny
   detail.

<Image src="ops.jpg" alt="but it works on *my* machine  joke" />

## **When Things Go Sideways**

- **Broke after an update?** Check if a major version sneaked in. Temporarily pin the version <br/>`"package": "1.2.3"`
  until you fix things.
- **Confused by symbols?** Use [semver.npmjs.com](https://semver.npmjs.com/) to test what versions your rules allow.

---

## **Quick Cheat Sheet**

| Symbol   | What It Means                             |  
|----------|-------------------------------------------|  
| `^1.2.3` | “Keep me up to date, but no big changes!” |  
| `~1.2.3` | “Only bug fixes, please.”                 |  
| `1.2.x`  | “Any patch version for 1.2.”              |  

---

## **Wrapping Up**

SemVer isn’t about memorizing rules—it’s about communicating changes clearly. Use `^` for flexibility, `~` for caution,
and exact versions when stability matters. <br/>And always, *always* check your `package-lock.json` into Git.

**Try this now:**

```bash  
npm outdated  
```  

See what updates are waiting? Update one with `npm update package-name` and see if your app still works. You’ve got
this! 🛠️

---  

*P.S. Sharing is caring. Forward this to a teammate who still edits `package.json` versions by hand. 😉*


A friendly, practical guide to SemVer in npm. Learn versioning rules, avoid dependency chaos, and manage updates with confidence.

Mastering npm and Semantic Versioning for Smarter Development


Writing clean, maintainable JavaScript isn't just about making your code work - it's about making it understandable. In
this comprehensive guide, we'll explore the essential naming conventions that can transform your JavaScript code from
merely functional to professionally polished.

## Why Naming Matters in JavaScript

Every time you write code, you're not just writing it for the computer - you're writing it for other developers (
**including your future self** ). Good naming conventions serve as a form of documentation, making your code self-explanatory
and reducing the cognitive load required to understand it.

## Core Principles of JavaScript Naming

### 1. Consistency Is Key

The most fundamental rule of naming in JavaScript is maintaining consistency throughout your project. Whether you choose
camelCase or snake_case, stick to it. Here's why:

- Reduces cognitive overhead for developers
- Makes code more predictable
- Simplifies maintenance and refactoring
- Improves team collaboration

### 2. Language Matters

While JavaScript is flexible enough to allow variable names in any language, stick to English. This ensures:

- Universal code readability
- Easier collaboration with international teams
- Better integration with existing codebases

### 3. The Case for Different Cases

JavaScript uses multiple naming conventions depending on the context:

- `camelCase` for variables, functions, and methods
- `PascalCase` for classes and constructor functions
- `UPPER_SNAKE_CASE` for constants
- `kebab-case` typically for CSS classes and HTML attributes

JavaScript’s built-in APIs use camelCase (e.g., getElementById), PascalCase for classes (e.g., Date), and UPPER_SNAKE_CASE for constants (e.g., Math.PI). Align your code with these patterns.

## Practical Naming Guidelines

### Variables and Functions

#### Boolean Variables

Boolean variables should start with an affirmative prefix, typically 'is' or 'has':

```javascript
// Bad ❌
const active = true;
const notAllowed = !user.checkAccess();

// Good ✅
const isActive = true;
const hasPermission = user.checkAccess();
```

> Another thing to remember at the conference is that the affirmative prefix shouldn't include a negation. This is because the negation operator (!) is most commonly used with Boolean values. So, a value named something like 'isNotAllowed' with the negation applied to it, '!isNotAllowed', can be quite misleading.

Naming recommendations for Boolean from [W3C](https://w3ctag.github.io/design-principles/#naming-booleans).

#### Functions and Methods

Function names should be verbs that clearly describe their action:

```javascript
// Bad ❌
function userData() {}

function total() {}

// Good ✅
function getUserData() {}

function calculateTotal() {}
```

### Collections and Arrays

Use plural nouns for arrays and collections:

```javascript
// Bad ❌
const userRoleList = ['admin', 'editor', 'viewer'];
const activeUserArr = new Set();

// Good ✅
const userRoles = ['admin', 'editor', 'viewer'];
const activeUsers = new Set();
```

### Classes and Objects

#### Class Names

Classes should use PascalCase and be noun phrases:

```javascript
// Bad ❌
class userService {
  constructor() {}
}

// Good ✅
class UserService {
  constructor() {}
}
```

#### Class Members

Avoid repeating the class name in member names:

```javascript
// Bad ❌
class UserProfile {
  updateUserProfile() {}

  deleteUserProfile() {}
}

// Good ✅
class UserProfile {
  update() {}

  delete() {}
}
```

### Constants and Enums

#### Constants

Use UPPER_SNAKE_CASE for true constants:

```javascript
// Bad ❌
const maxRetryAttempts = 3;
const apiBaseUrl = 'https://api.example.com';

// Good ✅
const MAX_RETRY_ATTEMPTS = 3;
const API_BASE_URL = 'https://api.example.com';
```

#### Enums

Use PascalCase for enum names and UPPER_SNAKE_CASE for enum values:

```javascript
// Bad ❌
const userRoles = {
  admin: 'admin',
  editor: 'editor',
  viewer: 'viewer'
};

// Good ✅
const UserRole = {
  ADMIN: 'admin',
  EDITOR: 'editor',
  VIEWER: 'viewer'
};
```

#### Maps
Also known as a dictionary data structure. This data structure is used for mapping one value to another.

```javascript
// Bad ❌
const userRole = {
  [AccountType.SUPERVISOR]: 'Supervisor',
  [AccountType.VISITOR]: 'Visitor',
}

const REDIRECTING = {
  '/teams': '/supervisor-panel',
  '/account': '/authenticate',
}

const UserPermissions = {
  [AccountType.SUPERVISOR]: [AccessLevel.USER_ADMINISTRATION, AccessLevel.TEAM_ADMINISTRATION],
  [AccountType.VISITOR]: [AccessLevel.PROFILE_MANAGEMENT],
}

// Good ✅
const userRoleToReadable = {
  [AccountType.SUPERVISOR]: 'Supervisor',
  [AccountType.VISITOR]: 'Visitor',
}

const pagePathToRedirectPath = {
  '/teams': '/supervisor-panel',
  '/account': '/authenticate',
}

const userRoleToPermissions = {
  [AccountType.SUPERVISOR]: [AccessLevel.USER_ADMINISTRATION, AccessLevel.TEAM_ADMINISTRATION],
  [AccountType.VISITOR]: [AccessLevel.PROFILE_MANAGEMENT],
}
```

## Common Pitfalls to Avoid

### 1. Including Types in Names

```javascript
// Bad ❌
const userArray = ['John', 'Jane'];
const nameString = 'John';

// Good ✅
const users = ['John', 'Jane'];
const name = 'John';
```

### 2. Ambiguous Abbreviations

```javascript
// Bad ❌
const usr = getUser();
const pwd = 'secret';

// Good ✅
const user = getUser();
const password = 'secret';
```

### 3. Inconsistent Naming Patterns

```javascript
// Bad ❌
const get_user = () => {};
const fetchData = () => {};
const retrieve_info = () => {};

// Good ✅
const getUser = () => {};
const fetchData = () => {};
const retrieveInfo = () => {};
```

### 4. Different Languages
```javascript
// Bad ❌
const ユーザー名 = "John";

// Good ✅
const userName = "John";
```

## Types & Interfaces

Names of types and interfaces should be written in `PascalCase` notation.

```typescript
// Bad  ❌
type TUser = {
  firstName: string
  lastName: string
}

interface userServiceInterface {
  findByEmail: (email: string) => User
}

// Good ✅
type User = {
  firstName: string
  lastName: string
}

interface UserServiceContract {
  findByEmail: (email: string) => User
}

interface IUserService {
  findByEmail: (email: string) => User
}
```

> When engineering teams choose to leverage both class-based types and abstract definitions within the same project, best practices suggest adding a distinguishing marker to the abstract definitions. Common prefix choices include `T` and `Contract`.

## Tools for Maintaining Naming Conventions

To help maintain consistent naming conventions, consider using:

1. [ESLint](https://eslint.org/) with naming convention rules
2. [Prettier](https://prettier.io/) for consistent formatting
3. IDE extensions for code style enforcement
4. Team code review guidelines focused on naming

## Time Tested Naming Naming Conventions
- [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html#naming)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript?tab=readme-ov-file#naming-conventions) 

## Conclusion

Good naming conventions are more than just style preferences - they're a fundamental aspect of writing maintainable,
professional JavaScript code. By following these conventions consistently and thoughtfully, you'll create code that's
easier to understand, maintain, and debug.

Remember, the goal isn't to follow these rules blindly, but to use them as guidelines to write more readable and
maintainable code. The best naming convention is one that your entire team understands and follows consistently.


Master JavaScript naming conventions with this comprehensive guide. Learn best practices for naming variables, functions, classes, and more to write cleaner, more maintainable code.

Serhii Shramko

Senior Software Engineer

Featured Posts

Generic Type Parameters in TypeScript

GraphQL Certified – How I earned my certification

My personal Linktree with Astro.js and Vercel

Advanced React

Custom Hooks Pitfalls

React Re-Renders

Projects

Quizlet QuickList

Udemy Reset Progress

Latest posts

Ignore files in Git without adding them to .gitignore

Semantic Versioning in npm

Why Are JavaScript Naming Conventions Important?