For years, API designers have quietly made the same compromise.

They start with a clean GET request:

GET /products?category=laptop&brand=acme HTTP/1.1
Host: api.example.com
Accept: application/json

Then the product team asks for price ranges, multiple brands, availability rules, nested attributes, full-text search, sorting, pagination, and user-specific constraints.

The URL begins to look less like an address and more like a programming language:

/products
└── filters
    ├── category = laptop
    ├── brands = [acme, contoso, globex]
    ├── price
    │   ├── minimum = 800
    │   └── maximum = 1800
    ├── specifications
    │   ├── memory >= 32 GB
    │   └── storage = SSD
    └── sort = rating desc, price asc

So the team moves the filters into JSON and sends them with POST:

POST /products/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "brands": ["acme", "contoso", "globex"],
  "price": { "min": 800, "max": 1800 },
  "specifications": {
    "memoryGb": { "gte": 32 },
    "storageType": "ssd"
  },
  "sort": ["-rating", "price"]
}

The endpoint works. The JSON is readable. The server returns products. But the method is now vague: without endpoint-specific knowledge, POST could mean a safe search, a payment, a message submission, or some other state-changing command.

In June 2026, RFC 10008 gave that operation its own method:

QUERY /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "brands": ["acme", "contoso", "globex"],
  "price": { "min": 800, "max": 1800 },
  "sort": ["-rating", "price"]
}

QUERY gives complex reads request content without giving up explicit read-only, retry, and caching semantics.

HTTP Methods Are Tiny Words With Large Contracts

GET, POST, PUT, and DELETE are method tokens with standardized meanings. Those meanings let clients, servers, caches, proxies, gateways, and monitoring systems reason about a request before they understand the application behind it.

The method is the first line of the contract:

HTTP request
├── method: What kind of operation is this?
├── target: Which resource is in scope?
├── fields: What metadata applies?
└── content: What representation accompanies the request?

Three properties matter to the QUERY story:

Idempotent does not mean identical responses. GET /products/42 can return $900 today and $850 tomorrow; GET remains idempotent because repeated reads request no additional state change. PUT and DELETE are also idempotent despite changing state. POST is not idempotent by definition because replaying it may repeat an action. PATCH may be idempotent in a specific use, but HTTP does not guarantee it.

The Gap Between GET and POST

GET is an excellent fit when query input fits naturally in the target URI:

GET /feed?q=http&limit=10&sort=-published HTTP/1.1
Host: example.org

It clearly communicates a safe, idempotent retrieval. Its responses work naturally with browsers, shared caches, CDNs, bookmarks, links, and observability tools.

Complex queries expose four practical limits:

• Clients, proxies, gateways, and servers impose different limits on request targets. RFC 9110 recommends support for at least 8,000 octets, but your path is only as tolerant as its most restrictive hop.
• Nested filters, arrays, ranges, and query languages become awkward once they are flattened via encoding into a query string.
• Request URIs often appear in logs, browser history, bookmarks, referrers, and monitoring tools. Request content can also be logged, but it is less widely exposed by default.
• With GET, every input combination becomes a distinct URI. That is useful for small filters and clumsy for large query documents.

POST avoids those limits because it expects request content. It also loses the generic signal that the operation is a safe, idempotent query.

That is the gap QUERY fills.

What QUERY Actually Means

RFC 10008 defines QUERY as a method that asks the target resource to perform a server-side query within that resource’s scope. The request’s content and Content-Type define the query. The target URI defines the resource being queried.

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$[?(@.country == "India" && @.status == "active")]

Here, /contacts establishes the scope. application/jsonpath tells the server how to interpret the content. The JSONPath expression describes the query.

A server must reject a QUERY request when Content-Type is missing or inconsistent with the content. That requirement is not decorative. The same bytes could have completely different meanings under application/json, application/sql, or application/jsonpath.

QUERY is not simply “GET with a body”

That phrase is a useful first approximation, but it hides the semantic difference.

• GET asks for a current representation of the resource identified by the target URI.
• QUERY asks the target resource to perform the operation described by the request content.

HTTP assigns no generally defined semantics to content in a GET request. Some implementations reject it, some ignore it, and intermediaries cannot safely assume what it means.

POST responses can be cached under specific conditions, but a stored response generally cannot satisfy a later POST. By design, a cached QUERY response can satisfy an equivalent later QUERY.

The Most Important Part: Caching the Content

A cache normally starts with the method and target URI when matching requests. That is insufficient for QUERY.

These two requests target the same URI but ask different questions:

QUERY /products HTTP/1.1
Content-Type: application/json

{"brand":"acme"}

QUERY /products HTTP/1.1
Content-Type: application/json

{"brand":"globex"}

If a cache considered only /products, it could return Acme results to a client asking for Globex. RFC 10008 therefore requires a QUERY cache key to incorporate the request content and related metadata.

A cache may normalize semantically insignificant differences before generating the key. For example, these JSON documents might mean the same thing:

{"brand":"acme","inStock":true}

{
  "inStock": true,
  "brand": "acme"
}

But normalization is dangerous when the cache and application disagree about meaning. A false match can return the wrong data. The safest initial implementation is often a deterministic query format plus a hash of the exact content and relevant metadata.

This is why “QUERY is cacheable” does not mean “every CDN supports it today.” A compliant QUERY cache must read the full request content and include it in matching.

A Query Can Become a GET-able Resource

RFC 10008 offers another useful pattern. A server can assign a URI to the query itself, to the result that was just produced, or to both.

HTTP/1.1 200 OK
Content-Type: application/json
Location: /products/stored-queries/42
Content-Location: /products/stored-results/17
ETag: "result-17"

[
  { "id": 7, "brand": "acme", "price": 1299 },
  { "id": 9, "brand": "contoso", "price": 1499 }
]

The two response fields serve different purposes:

The distinction matters when the underlying data changes. A stored query can produce a newer answer. A stored result can represent the answer from a particular execution.

QUERY also supports conditional requests. Once a client has an ETag or Last-Modified validator, it can ask for results only if they changed. If the server supplies a Location for an equivalent resource, subsequent GET requests can make that flow simpler and more widely compatible.

Safe Retries Are a System Design Feature

Imagine a client sends a complex search and the connection drops before the response arrives.

With an application-specific POST endpoint, the client cannot infer from the method alone whether retrying might repeat a state change. It needs out-of-band knowledge of that endpoint’s behavior.

QUERY carries the answer in the protocol. It is idempotent, so clients and intermediaries can repeat it after a connection failure without introducing a second requested state change.

Connection fails
├── POST
│   └── Retry only with endpoint-specific knowledge or safeguards
└── QUERY
    └── Retry is allowed by the method's idempotent semantics

Servers Can Advertise QUERY Support

The RFC also defines the Accept-Query response field. A resource can use it to advertise the media types it accepts as query content:

HEAD /products HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Accept-Query: application/json, application/jsonpath

This tells the client that the resource supports QUERY with JSON or JSONPath content. Content-Type identifies the query format, while Accept lists the desired response formats.

Request format                         Response format
Content-Type: application/json         Accept: application/json
             │                                  │
             └── how to read the query          └── how to return the result

Why You Should Not Replace Every GET Tomorrow

QUERY is now standardized. Standardization and universal deployment are not the same event.

An HTTP request usually crosses a chain of components:

Client
  └── SDK or browser
      └── corporate proxy
          └── CDN or edge cache
              └── WAF
                  └── API gateway
                      └── application server
                          └── route handler

Every component must either understand QUERY or pass it through correctly. Before adopting it, verify the boring path:

• The client can send an extension method with content.
• Proxies, firewalls, and gateways do not reject or rewrite it.
• The application server can route it.
• Cache behavior includes content and relevant metadata in the key.
• Authentication and authorization are evaluated before query execution.
• Logs and tracing systems label it correctly without exposing sensitive content.
• Rate limits account for query cost, not merely request count.
• Cross-origin browser calls complete the required CORS preflight.

There is also a security misconception worth removing:

Request content is less likely than a URI to appear in routine logs. It is not automatically private.

Use HTTPS. Redact sensitive fields. Validate the query language. Apply authorization at the data level. Limit depth, joins, result size, and execution time. A beautifully semantic method can still carry an expensive or malicious query.

The Bigger Lesson Is Not About One New Word

HTTP methods help distributed systems communicate intent. GET says, “Give me a representation of this resource.” POST says, “Process this content according to this resource’s rules.” QUERY now says, “Safely process this query and give me the result.”

Simple filters should remain GET requests. Existing POST search endpoints will not suddenly stop working. But when a read operation becomes too expressive for a URI and your request path supports it, developers no longer have to choose between readable content and honest HTTP semantics.

The gap finally has a method.

The one sentence to remember: QUERY is a safe, idempotent, content-bearing HTTP method for complex server-side queries.

References

• RFC 10008: The HTTP QUERY Method
• RFC 9110: HTTP Semantics
• RFC 9111: HTTP Caching

Think of npm as downloading a movie and npx as streaming it on Netflix.

With npm, you download something, keep it in your collection, and use it whenever your project needs it. With npx, you press play, use the thing right now, and move on without deliberately adding it to your collection.

In terminal terms:

# Download and keep a tool in this project
npm install --save-dev eslint

# Run a tool directly
npx eslint .

That analogy is memorable, and it gets the big idea right:

npm manages packages. npx executes package commands.

But Netflix does not quite explain why npx sometimes uses a package you already installed, why remote packages remain in a cache, or how a command such as npx skills add knows what add means.

So let us start with the simple analogy and then go one layer deeper.

npm vs. npx in 30 Seconds

The distinction is not “npm can never run code” or “npx never downloads code.” npm can run scripts, and npx may fetch a missing package before executing it.

The real distinction is managing a dependency versus launching a package executable.

npm: Download It, Record It, Keep It

npm is the package manager for the Node.js ecosystem. Its job is much larger than downloading files. It can install, update, remove, publish, audit, and configure packages, as well as run commands defined by a project.

Install a runtime dependency:

npm install express

Install development tools:

npm install --save-dev eslint prettier vitest

npm places the packages in the project’s dependency tree, records the relationship in package.json, and updates package-lock.json. The project now has an explicit, reviewable dependency on those versions.

That is the “download the movie” side of the analogy: the package becomes part of the project’s collection.

npx: Find the Command and Press Play

npx is for executing a command supplied by an npm package:

npx eslint .
npx prettier --write .
npx skills add vercel-labs/agent-skills

If a matching package is already installed locally, npx uses that project’s version. If it is missing, npm can fetch it into its cache, expose its executable to the process, and run it.

This means npx tool does not automatically mean “download the latest version.” Local versions take priority when they match the request.

What Is npm exec - How Is It Related to npx?

The shortest honest answer is:

npm exec is npm's built-in command for running a package executable.
Modern npx uses npm exec underneath.

They perform the same core job, but calling npx a perfect alias hides a small compatibility detail: the two command forms parse options differently.

Why Do Both Commands Exist?

npx began as a standalone tool created to solve a common annoyance: developers wanted to run package commands without installing every CLI globally or typing paths such as ./node_modules/.bin/eslint.

It became popular enough to be bundled with npm 5.2 in 2017. Then npm 7 moved that capability into the main npm CLI as npm exec. The standalone npx package was deprecated, and the npx binary was rewritten to use npm exec while preserving familiar behavior for existing users. The official npm documentation describes this as a compatibility layer around the same execution machinery.

Both names remain because npx is short, familiar, and embedded in years of documentation, tutorials, scripts, and developer muscle memory.

Same Engine, Slightly Different Argument Parsing

For ordinary commands, these express the same intent:

npx eslint .
npm exec -- eslint .

The double dash in the second command means: “npm, stop parsing options here; pass the rest to the command being executed.”

Consider TypeScript’s --init flag:

# With npx, arguments after the package name go to the package command
npx tsc --init

# With npm exec, this form makes the boundary explicit
npm exec -- tsc --init

The placement matters. npm exec tsc -- --init is an easy form to guess, but the documented, unambiguous pattern is npm exec -- tsc --init: put -- before the package command and everything that follows belongs to that command.

There is no performance prize for choosing one spelling. Use npx when you want the familiar shorthand. Use npm exec when explicit npm syntax, workspaces, --package, or careful argument boundaries make the longer form clearer.

What Happens After Either Command?

When you run either form, the useful mental model i

1. npm makes locally installed package executables available to the command.
2. If the requested package is missing locally, npm normally prompts before fetching it in an interactive terminal.
3. The missing package is installed into a directory inside npm’s cache, and that directory is added to the launched process’s PATH.
4. npm infers the executable from the package’s bin field.
5. The executable starts and receives the remaining arguments.

No, the Download Is Not Immediately Deleted

The streaming analogy, “npm downloads the movie, npx streams it” sounds elegant, but it is technically misleading.

When npx needs a remote package, npm uses its internal package cache. The fetched files can remain there so later executions do not necessarily download everything again. npm provides cache preferences such as prefer-online, prefer-offline, and offline, which is another clue that this is caching, not instant deletion.

From your project’s perspective, however, the package remains transient:

• It is not added to your project’s dependencies or devDependencies.
• It is not installed into your project’s node_modules tree.
• It is not recorded in your project’s lockfile.

There is one crucial caveat:

npx may leave your dependency manifest untouched, but the program it executes can still change anything your user account is allowed to change.

npx skills add ... is supposed to write skill files into your workspace. A scaffolder creates an entire project. A formatter rewrites source files. A malicious CLI could do much worse.

npx is a launcher, not a sandbox.

npm, npx, and npm run Are Three Different Ideas

Here is the distinction that clears up most confusion.

npm install: Put a Package in the Project

npm install --save-dev eslint

This downloads ESLint into the project’s dependency tree, records it in devDependencies, and updates the lockfile. npm also creates the platform-appropriate link or command shim for ESLint's executable.

Now the project owns an explicit, reviewable relationship with ESLint.

npx / npm exec: Launch a Package Executable

npx eslint .
# equivalent intent
npm exec -- eslint .

Because ESLint is already installed locally, npm uses the project’s version. It does not need to fetch a second copy.

That leads to a useful rule: npx tool does not mean “run the latest tool.” An unversioned package name can match the version already installed in the project. If you explicitly request tool@1.2.3, a local dependency only matches when its name and version match that request exactly.

npm run: Launch a Script Named by Your Project

Suppose your package.json contains:

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

You can run:

npm run lint
npm run lint:fix

npm run looks up lint in your project's scripts object. It also adds node_modules/.bin to the script's PATH, which is why the script can say eslint instead of ./node_modules/.bin/eslint. This behavior is documented in the official npm run guide.

The difference is small but important:

For a command you use repeatedly, an npm script gives the operation a stable name and keeps its flags in version control. Your teammate should not need to remember the exact lint command from Slack history.

Case Study: What Does npx skills add Actually Mean?

Now we can decode the command that inspired the question:

npx    skills    add    vercel-labs/agent-skills
│      │         │      │
│      │         │      └─ argument: the source to add
│      │         └──────── subcommand interpreted by Skills
│      └────────────────── npm package and executable name
└───────────────────────── find/fetch and launch the executable

The easy mistake is to assume that add is an npm script. It is not.

An npm package becomes a command-line tool when its package.json exposes one or more files through the bin field. The real skills package currently includes this mapping in its package.json:

{
  "name": "skills",
  "bin": {
    "skills": "./bin/cli.mjs",
    "add-skill": "./bin/cli.mjs"
  }
}

npm sees that the package exposes a command named skills and launches ./bin/cli.mjs. Everything after skills is passed to that program.

Node exposes those values through process.argv. A deliberately tiny version of the CLI might read them like this:

const [, , command, source] = process.argv;

if (command === "add") {
  console.log(`Adding skills from ${source}`);
}

The actual Skills CLI is more sophisticated, but the contract is the same:

command = "add"
source  = "vercel-labs/agent-skills"

npx is responsible for making the executable available and starting it. The Skills CLI is responsible for deciding what add means and writing the requested skill files.

A Practical Rulebook

Use npm install when the package is part of the project:

npm install express
npm install --save-dev eslint prettier vitest

Use npm run for repeatable project commands:

npm run lint
npm test
npm run build

Use npx or npm exec for a direct executable, especially when it is already installed locally:

npx eslint .
npm exec -- prettier --check .

Use a one-off remote execution for a generator or diagnostic tool you do not want to keep as a project dependency:

npx skills add vercel-labs/agent-skills

For project creation, npm also offers npm create, which is an alias of npm init and transforms an initializer into an npm exec operation. For example:

npm create vite@latest my-app

Under the hood, npm resolves the corresponding create-vite initializer and runs its executable. The npm init documentation spells out that transformation.

And if an old tutorial tells you to start every React app with npx create-react-app, note that the React team deprecated Create React App for new apps in February 2025. The npx lesson remains valid; the recommended React tooling has moved on.

The Security Footnote That Should Not Be a Footnote

This command can download code and execute it:

npx some-package

A typo can point at a different package. An unpinned package can resolve to a newer release than the one you used last time. The confirmation prompt helps prevent accidents, but clicking y does not make the code trustworthy. In non-interactive or CI environments, npm may proceed without that prompt.

A safer working habit is:

1. Verify the package name, publisher, repository, and command before running it.
2. Prefer a locally installed, lockfile-controlled dependency for recurring project work.
3. Pin an exact version when repeatability matters:

npx some-cli@1.2.3 do-the-thing

1. This pins the requested CLI release, not necessarily its entire transitive dependency tree. For stronger reproducibility, install it as a project dependency, commit the lockfile, and use npm ci in automation.
2. Treat -y or --yes as “skip the prompt,” not “make this safe.”
3. Never assume npx limits what the launched program can read, write, or send over the network.

Convenience and trust are separate decisions.

Modern GenAI Software Development Environments (SDEs) such as OpenAI’s Codex, Claude Code, Cursor, and similar tools increasingly use modular guidance and capability packs. These Agent Skills are self-contained directories discovered up front and loaded only when relevant. In SDLC terms, they encode repeatable workflows for planning, implementation, testing, review, release, and maintenance.

1. The Anatomy: What is a Skill?

Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

At its core, a skill is a discoverable folder containing a SKILL.md file. In Codex, repo-scoped skills commonly live under .agents/skills, while user-level skills can live under $HOME/.agents/skills. Other SDE hosts may use different locations.

Here, the SDE host is the application or runtime around the model: the IDE, CLI, cloud workspace, or agent platform that discovers skills, manages context, runs tools, and enforces permissions.

A standard code-generation skill can look like:

generate-code-skill/
├── SKILL.md          (Required: metadata + instructions)
├── scripts/          (Optional: executable Python, Bash, or other code)
├── references/       (Optional: documentation and detailed guidance)
├── assets/           (Optional: templates, examples, static resources)
└── agents/
    └── openai.yaml   (Optional: UI metadata, policy, dependencies)

For local authoring, a skill can be a plain folder. For distribution or hosted execution, systems may package skills as zip files, plugins, or uploaded bundles. The packaging varies; the core idea is to keep reusable instructions and supporting files together.

2. The Trigger: How the AI Decides to Act

If an agent has 50 different skills, it should not read all of their instructions at once. That would waste context and dilute the prompt. Skills solve this with progressive disclosure.

The anchor of every skill is the SKILL.md file, which starts with a YAML frontmatter block:

---
name: auto-linter
description: Use when Python files need formatting, lint fixes, or syntax-cleanup checks before tests are run.
---

The Translation Layer:
Models do not browse local folders on their own. The host application acts as the bridge:

1. It scans available skills.
2. Gives the model a compact inventory of skill names, descriptions, and paths.
3. Loads the full instructions only when the model selects a skill.

Some agent frameworks may represent this inventory as tool metadata or schemas.

When you give the agent a prompt like, “Clean up the syntax in auth.py", the model compares your intent with these short descriptions and chooses the most relevant skill.

Developer Note: Write highly distinct descriptions. If one skill says “sends a message” and another says “emails a user,” the model may not have enough signal to distinguish them. This Tool Collision can cause the wrong skill to be selected.

3. The Brain: The Markdown Body

After selection, the host loads the rest of SKILL.md into the active task context. This markdown body becomes a focused instruction layer for that workflow.

If you are building a generate-python-test skill, the body tells the model how to do the job:

• Framework rules: “Always use pytest.”
• Constraints: “Mock all external API calls.”
• Examples: A few-shot code block showing a perfect, team-approved test.

This is where teams encode business logic, coding standards, review norms, and output formats.

4. The Muscle: Executing Code & Self-Correction

A common misconception is that the LLM runs code by itself. It doesn’t. The model handles reasoning and intent; the host application runs commands through tools, shells, or sandboxes and returns the output.

This brings us to the scripts/ directory. This folder can contain local executables such as lint.sh, run_tests.py, or validate_schema.py. These scripts act as deterministic checks around the model's work.

The Self-Correction Loop:
What happens if the model writes Python code with a missing quote, and scripts/run_tests.sh fails?

1. The script returns an exit code and error output.
2. The host application captures the raw stdout / stderr.
3. The error is passed back into the model’s active context.
4. The model revises the code and tries again, subject to the host’s permissions, limits, and approval flow.

This loop repeats only when the host, workflow, and permissions allow it. Scripts raise the floor by making failures visible and concrete; they do not guarantee perfect code.

5. The Library: Providing Context

We can’t forget the references/ folder. This holds static files that give the model extra context. It acts as a cheat sheet containing:

• boilerplate_test.py: a blank template file.
• style_guide.md: naming conventions and review rules.
• mock_data.json: pre-made dummy data to reduce hallucinated user information.

Some skills also include assets/ for output files such as document templates, icons, sample fixtures, or reusable boilerplate.

6. Orchestration: The ReAct Loop

How does an agent complete a larger ticket like, “Audit my repository for deprecated APIs and draft a migration plan”?

The work becomes a model-host partnership, often resembling the ReAct (Reasoning and Acting) loop. Workflow instructions guide the task, but the agent still chooses actions as new information arrives.

1. Analyze & plan: The model breaks the task into a checklist.
2. Match: It selects the first skill, such as scan-codebase.
3. Execute: The host pauses generation, runs the approved tool or script, and returns the output.
4. Review: The model evaluates the result and decides whether to continue, revise, or use another skill.

The model makes choices on the fly, while the host application manages execution, files, permissions, and tool output.

7. Security & Scoping: Keeping the Agent in Check

The Bouncer: Skill Scope and Policy

To prevent an agent from using unrelated skills, SDEs scope what the model can see. In a host-agnostic setup, skills are usually discovered from configured locations: the current project, the user’s personal library, organization-provided packs, or system defaults.

This is where workspace-config.json fits. It is not the skill; it is workspace-level policy that tells the host which skill sources to scan, which skills to enable or disable, whether a skill can be invoked automatically, and which actions need approval.

Think of the split this way:

• A skill folder says, “Here is a reusable workflow.”
• A workspace config says, “Here is what this workspace allows the agent to see and do.”

The host decides which skills are available, which metadata enters the prompt, and which actions require approval.

The Sandbox: Constrained Execution

What happens if an AI agent reads a malicious prompt hidden in an open-source library that tells it to run rm -rf /?

Modern Hosts combine several controls: sandboxed command execution, workspace boundaries, network restrictions, explicit approvals, and command rules. For example, Codex documents platform-native sandboxing for local execution: macOS uses Seatbelt, Linux/WSL2 can use bubblewrap, and Windows uses native Windows sandboxing.

The practical rule is: give the agent the smallest useful workspace, restrict network and filesystem access, require approvals for risky actions, and treat third-party skills or scripts like code you need to review.

Conclusion

The shift from massive system prompts to modular skills makes AI software engineering agents more practical across the SDLC:

1. Skills package repeatable workflows: A skill bundles instructions, scripts, references, and assets for a focused task.
2. Progressive disclosure keeps context focused: The host shows compact metadata first, then loads the full SKILL.md only when needed.
3. The host turns reasoning into action: The model plans and chooses, while the SDE host manages files, tools, command execution, approvals, and feedback loops.
4. Supporting files make workflows durable: scripts/ provide repeatable checks, while references/ and assets/ provide standards, templates, examples, and reusable context.
5. Workspace policy controls the blast radius: A config layer, such as workspace-config.json, decides which skills are visible, what they may access, and which actions need approval.
6. Orchestration connects the pieces: Larger SDLC tasks work through a ReAct-style loop of planning, selecting skills or tools, observing results, and revising next steps.
7. Guardrails make the pattern trustworthy: Scope rules, sandboxing, network limits, and approvals keep agent workflows constrained enough to use safely.

In the Part -2, we added support for the fetch API’s options object and baked in the ability to refetch data into our hook.

Using The Final Implementation of our useFetch Hook

Now, whether you’re fetching data or sending it, the component logic remains simple, yet elegant.

Here is the final, complete code for our useFetch hook:

import { useState, useEffect, useCallback } from 'react';
export function useFetch<T>(url: string, options?: RequestInit) {
    const [data, setData] = useState<T | null>(null);
    const [loading, setLoading] = useState(false);
    const [error, setError] = useState<Error | null>(null);

    const fetchData = useCallback(async (abortSignal?: AbortSignal) => {

        const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
        // const fetchData = async () => {
        setLoading(true);
        setError(null);
        try {
            await sleep(5000);
            const response = await fetch(url, {
                ...options,
                signal: abortSignal || options?.signal,
            });
            if (!response.ok) {
                throw new Error(`HTTP error! Status: ${response.status}`);
            }
            // Handle cases with no response body
            if (response.status !== 200) {
                setData(null);
            } else {
                const result = (await response.json()) as T;
                setData(result);
            }
        } catch (error) {
            if (error instanceof Error && error.name === 'AbortError') {
                console.log('Fetch aborted');
                return;
            }
            if (error instanceof Error) {
                setError(error);
            } else {
                setError(new Error('An unknown error occurred'));
            }
        } finally {
            setLoading(false);
        }
        // We stringify the options object to prevent infinite loops
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [url, JSON.stringify(options || {})])
    useEffect(() => {
        const controller = new AbortController();
        fetchData(controller.signal);
        return () => {
            controller.abort();
        };
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [fetchData]);
    return { data, loading, error, refetch: fetchData };
}

Fetching a list of users (GET):

interface User {
  id: number;
  name: string;
}
function UserList() {
  const { data, loading, error, refetch } = useFetch<User[]>('/api/users');
  // ... render logic
}

Creating a new user (POST):

function AddUserForm() {
  const newUser = { name: 'Jane Doe', email: 'jane@example.com' };
  
  const options = {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newUser),
  };
const { data, loading, error, refetch } = useFetch<User>('/api/users', options);
  // ... render logic
}

Conclusion

By building this hook, we’ve achieved the three core benefits of a great abstraction:

• Reusability: Use one hook for any HTTP request.
• Encapsulation: The complex logic of fetching, cancellation, and state management is hidden away.
• Type Safety: Generics give us confidence in our data structures and prevent bugs.

Happy Coding!

In the Part -1, we implemented a very basic useFetch hook, with the ability to make GET calls and handle request cancellations.

Chapter 4: Adding Fetch Options

Our hook currently supportsGET requests. In order to supportPOST, PUT or sending custom headers we can need to accept the fetch API's options object.

TypeScript provides a built-in type for this: RequestInit. We’ll add it as an optional parameter.

function useFetch<T>(url: string, options?: RequestInit) {
  // ...
}

However, if we add the options object to our useEffect dependency array, it will cause an infinite loop of API calls, because an object is a new reference on every render.

The solution is to give the dependency array a stable, primitive value: a string. JSON.stringify() is perfect for this.

Chapter 5: Adding a refetch Capability

Our hook runs automatically when the component mounts or when its dependencies (url or options) change.

But what if we want to control the data fetch? For example, implementing a “Refresh” button or more importantly, scenario where a user submits new data.

A refetch function makes this possible. It gives our hook an imperative "remote control" to trigger the fetch whenever we need it.

Exposing the Fetch Logic

Our fetching logic currently lives inside a function that’s created within useEffect. To make it callable, we need to move it outside. However, if we define it as a plain function inside our hook, it will be recreated on every single render. This would cause our useEffect to run in an infinite loop.

The solution is: useCallback hook. It will memoize the function, guaranteeing that we get the exact same function instance between renders unless its dependencies change.

The Implementation

We’ll wrap our fetchData logic in a useCallback hook. The dependencies for this callback will be the same as our old useEffect dependencies: url and the stringified options.

The useEffect then becomes much simpler: its only job being to call the memoized fetchData function on the initial render and handling the cleanup. Finally, we return our new refetch function from our hook.

import { useState, useEffect, useCallback } from 'react';

function useFetch<T>(url: string, options?: RequestInit) {
  // ... (useState declarations for data, loading, error)

  // 1. Wrap the fetching logic in useCallback
  const fetchData = useCallback(async () => {
    setLoading(true);
    // ... all the try/catch/finally logic
  }, [url, JSON.stringify(options || {})]);

  // 2. useEffect now just calls the function and handles cleanup
  useEffect(() => {
    const controller = new AbortController();
    // We pass the signal to a slightly modified fetchData
    // (See full code in the final version for this detail)
    fetchData(controller.signal);

    return () => {
      controller.abort();
    };
  }, [fetchData]); // The dependency is now the stable, memoized function

  // 3. Return the function so the component can use it
  return { data, loading, error, refetch: fetchData };
}

Here’s an example implementation of the Refresh button:

import { useFetch } from './useFetch';

function UserList() {
  // We just grab 'refetch' from our hook
  const { data, loading, error, refetch } = useFetch<User[]>('/api/users');

  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h1>User List</h1>
      <button onClick={() => refetch()} disabled={loading}>
        {loading ? 'Refreshing...' : 'Refresh'}
      </button>

      <ul>
        {/* ... render the list */}
      </ul>
    </div>
  );
}

Our useFetch hook is ready. In Part -3, we’ll conclude with the complete implementation and demonstrate how to use it effectively.

A step-by-step guide to creating a reusable, and type-safe custom hook for all your data fetching needs using TypeScript.

This is a 3-part series. If you want to skip straight to the full code and demo, jump to Part-3.

If you’ve been working with React for any length of time, you’ve seen this pattern a dozen times. You need to fetch some data, so you reach for useState and useEffect.

function UserProfile() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
      fetch('/api/user/1')
        .then(res => res.json())
        .then(data => setUser(data))
        .catch(err => setError(err))
        .finally(() => setLoading(false));
    }, []);
    // ... render logic
}

It works. But then you need to fetch a list of posts. Then a list of comments. Soon, you’re copying and pasting this same block of logic everywhere, changing only the URL and the state variable.

Today, we’re going to stop writing boilerplate fetch logic and build one powerful, reusable useFetch hook that will handle almost all of our data-fetching needs. We'll build it from the ground up, piece by piece.

Chapter 1: The Foundation and Managing State

Before we can fetch anything, we need to know what information to track. For any given data request, there are three critical pieces of state:

1. data: The JSON response when the fetch is successful.
2. loading: A boolean to know if the request is in progress.
3. error: An error object if the fetch fails.

The idea here is to make our hook work with any data structure: users, posts, products, etc. while keeping full type safety. This is the perfect job for Generics.

We’ll define our hook with a generic type placeholder, <T>.

import { useState } from 'react';

function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState<boolean>(false);
  const [error, setError] = useState<Error | null>(null);
  // We'll add the fetch logic next...
  return { data, loading, error };
}

This simple foundation is both flexible and completely type-safe.

Chapter 2: making the API Request with useEffect

Data fetching is a side effect. It’s an action that reaches outside of React into the browser’s APIs. The useEffect hook is the perfect tool for this.

The logic follows a clear path:

1. Set loading to true and errors to nullbefore the request starts.
2. Use a try block to await the fetch and set the data on success.
3. Use a catch block to capture any errors.
4. Use a finally block to set loading back to false, no matter what.

function useFetch<T>(url: string) {
  // useState declarations...

  useEffect(() => {
    const fetchData = async () => {
      setLoading(true);
      setError(null); // Clear previous errors
      try {
        const response = await fetch(url);
        if (!response.ok) {
          throw new Error(`HTTP error! Status: ${response.status}`);
        }
        const result = await response.json() as T; // Assert the type
        setData(result);
      } catch (error) {
        if (error instanceof Error) {
          setError(error);
        } else {
          setError(new Error('An unknown error occurred'));
        }
      } finally {
        setLoading(false);
      }
    };
    fetchData();
  }, [url]); // Re-run the effect if the URL changes
  return { data, loading, error };
}

Now we have a fully functional hook. The component that uses it doesn’t need to know about async/await or error handling; it just gets the final state.

Chapter 3: Handling Cancellations

Our hook has a subtle bug. If the component that uses useFetch unmounts while the request is still in flight, React will show a warning: "Can't perform a React state update on an unmounted component." This is a memory leak.

We need to cancel the request on cleanup. The useEffect hook has a built-in mechanism for this: the cleanup function. If you return a function from useEffect, React will run it when the component unmounts.

We’ll use the browser’s AbortController API to make our fetch cancellable.

// Inside useFetch...
useEffect(() => {
  // 1. Create a controller for this effect run
  const controller = new AbortController();

const fetchData = async () => {
    setLoading(true);
    // ...
    try {
      // 2. Pass its signal to the fetch options
      const response = await fetch(url, { signal: controller.signal });
      // ...
    } catch (error) {
      // 3. IMPORTANT: Ignore the AbortError
      if (error instanceof Error && error.name === 'AbortError') {
        console.log('Fetch aborted');
        return; // Don't set state, just exit
      }
      // ... handle other errors
    }
    // ...
  };
  fetchData();
  // 4. Return the cleanup function to abort the request
  return () => {
    controller.abort();
  };
}, [url]);

When controller.abort() is called, the fetch promise rejects with an AbortError. We catch this error but do not set our error state. An aborted request isn't a real error; it's our code cleaning up as intended. The user has already navigated away, so we don't want to show them a confusing error message.

In this part, we built a simple useFetch hook. In Part -2, we’ll refine it further by adding support for fetch options and a refetch mechanism.

A deep dive into the subtle traps of React’s most powerful hook and why one infinite loop can feel very different from another.

You build a simple component, add a bit of state, and throw in a useEffect for good measure. You hit save and suddenly the browser slows down, the UI lags, and you’re left wondering what just happened.

Chances are, you’ve run into one of the classic pitfalls of the useEffect hook. It’s one of React’s most powerful tools, but also one of the easiest to misuse.

In this article, I’ll walk you through two different ways an infinite loop can sneak into your code and how each behaves in its own unique way.

The First Trap: The “Missing” Dependency Array

Let’s start with a simple goal: Generate a random number when a component loads. The first attempt might look something like this:

import React, { useState, useEffect } from 'react';

const NumberGenerator = () => {
  const [randomNumber, setRandomNumber] = useState<number>(0);
  useEffect(() => {
    // Let's set a random number!
    setRandomNumber(Math.floor(Math.random() * 10));
  }, ); // Notice the dependency array is missing

  return <h1>Random Number: {randomNumber}</h1>;
};

“Will this create a render loop?” Yes. Absolutely. This is the most common useEffect mistake.

But Why?

If you don't provide the second argument (dependency array) while defining your useEffect hook, the effect function will run after every single render.

Here’s the vicious cycle that ensues:

• Component Renders: The component renders for the first time.
• useEffect Runs: Because there is no dependency array.
• State is Updated: setRandomNumber() is called, which updates the component's state.
• Re-render is Triggered: Any state update in React causes the component to re-render.
• Step-1 Again (Loop): The component re-renders, which causes the effect to run again, which updates the state again, and so on, forever.

The Observation: “But it’s not hanging my application!”

Here’s where things get interesting. When I ran this code, my app became sluggish and my CPU spiked, but the browser tab didn’t completely freeze. I could still click things, even if they were slow to respond.

This is because a React render loop isn’t the same as a traditional while (true) {} loop. A while loop blocks the JavaScript main thread entirely. The browser can't do anything else.

A React loop, however, is a series of scheduled updates. Between each render -> effect -> setState cycle, React yields control back to the browser for a brief moment. The browser gets a millisecond to breathe before React starts the next render. So it's less of a "freeze" and more of a "hyperactive" state that suffocates the browser with endless work.

How to fix it: To run an effect only once when the component mounts, provide an empty dependency array [].

useEffect(() => {
  setRandomNumber(Math.floor(Math.random() * 10));
}, []); // Empty array implies: "will run only once"

The Second Trap: The Self-Destructive Dependency

What if I want the effect to run only when randomNumber itself changes?

import React, { useState, useEffect } from 'react';

const NumberGenerator = () => {
  const [randomNumber, setRandomNumber] = useState<number>(0);
  useEffect(() => {
    // Let's set a new random number!
    setRandomNumber(Math.floor(Math.random() * 10));
  }, [randomNumber]); // The effect now depends on the state it changes

  return <h1>Random Number: {randomNumber}</h1>;
};

Again, the question arises; “Will this create a render loop?” Yes, and this one is even more insidious.

But Why?

You’ve explicitly told React: “Hey, I want you to run this effect whenever randomNumber changes." But the effect's one and only job is to change randomNumber.

This creates an inescapable feedback loop:

• The component renders.
• After rendering, useEffect runs for the first time.
• It calls setRandomNumber(), updating the state.
• This triggers a re-render.
• After the re-render, React compares the old randomNumber with the new one. They are different!
• Because a dependency changed, React runs the effect again.
• Go to Step 3.

The Observation: “This one hangs my application.”

Running this second scenario, my application felt much more frozen. User input was completely ignored. It felt like a true “hang.”

While both scenarios are infinite loops, the second one creates a tighter, more insistent cycle. The update is conditional on the very state it produces. The React scheduler sees this tight coupling: a state update immediately invalidating the condition that allowed it to rest and can get locked into a high-priority loop that gives the browser even less time to breathe than the first scenario.

It’s the difference between a predictable, rhythmic chaos (Scenario 1) and a self-validating paradoxical loop that starves the event queue more aggressively (Scenario 2).

But honestly, this is an academic difference. It’s like debating which of two flat tires is flatter. Both are critical bugs.

The Golden Rules of useEffect

This journey taught me two unforgettable rules for working with useEffect.

1. The Dependency Array is NOT Optional. It Defines Your Logic.

• No Array useEffect(() => {}): Runs after every render. Use this only if you truly want to react to every single prop or state change.
• Empty Array useEffect(() => {}, []): Runs only once after the initial render. Perfect for one-time setups, data fetching, or subscriptions.
• Populated Array useEffect(() => {}, [a, b]): Runs after the initial render, and then only if a or b have changed since the last render. This is the heart of reactive programming in React.

2. An Effect Should Not Set a State That Is in Its Own Dependency Array.

This is the definition of the self-destructive loop we saw in Scenario-2. The job of an effect is to cause a side effect in response to a change, not to cause the change that it responds to.

Happy coding!

You have a component that’s re-rendering way too often. You identify an expensive child component, wrap it in React.memo .But then you open the profiler, and it’s still re-rendering every single time the parent does.

It’s not broken, but it’s being tripped up by one of JavaScript’s fundamental truths: functions are objects. And in the world of React, that little detail can cost you dearly in performance.

Today, we’ll unravel this mystery and show how the useCallback hook is the key to making your optimizations actually work.

When React.memo Fails

We have a ParentComponent that holds some state, and it passes a function down to a ChildComponent. To prevent the child from re-rendering unnecessarily, we've wrapped it in React.memo.

As a quick refresher, React.memo is a higher-order component that tells React, "Don't re-render this component unless its props change." It does this by doing a shallow comparison of the old props and the new props.

Here’s our code:

import React, { useState } from 'react';

// An "expensive" child component we want to protect from re-renders
const ChildComponent = React.memo(
  ({ onButtonClick }: { onButtonClick: () => void }) => {
    console.log("ChildComponent is re-rendering! Why?");

    return <button onClick={onButtonClick}>Click Me</button>;
});

const ParentComponent = () => {
  const [count, setCount] = useState(0);

  // This function is passed as a prop to the child
  const handleButtonClick = () => {
    console.log("Button was clicked!");
  };

  return (
    <div>
      {/* This button's only job is to cause the Parent to re-render */}
      <button onClick={() => setCount(count + 1)}>
        Re-render Parent: {count}
      </button>
      <ChildComponent onButtonClick={handleButtonClick} />
    </div>
  );
};

When you run this and click the “Re-render Parent” button, you’ll see ChildComponent is re-rendering! Why? in the console every single time.

But why? The child’s props haven’t really changed, have they?

The problem lies in how JavaScript handles equality. Every time ParentComponent re-renders, the handleButtonClick function is re-created from scratch.

It might do the same thing, but it’s a brand new function in memory. For React.memo's shallow comparison, oldProps.onButtonClick === newProps.onButtonClick is always false. The old function and the new function are two different objects (Different addresses in memory).

useCallback to the Rescue

This is the exact problem useCallback was designed to solve. It lets us memoize a function, giving it a stable identity across renders.

Let’s fix our ParentComponent:

import React, { useState, useCallback } from 'react';

// ChildComponent remains the same
const ChildComponent = React.memo(/* ... */);

const ParentComponent = () => {
  const [count, setCount] = useState(0);

  // This function is now MEMOIZED
  const handleButtonClick = useCallback(() => {
    console.log("Button was clicked!");
  }, []); // The dependency array

  return (
    <div>
      <button onClick={() => setCount(count + 1)}>
        Re-render Parent: {count}
      </button>
      <ChildComponent onButtonClick={handleButtonClick} />
    </div>
  );
};

By wrapping our function definition in useCallback and providing an empty dependency array [], we're telling React to create this function once, on the very first render, and then give back that exact same function instance every other time.

Now, when the parent re-renders, React.memo compares the onButtonClick prop and finds that it is the exact same function instance as before.

The Plot Twist: The Dependency Array and Stale Closures

If we modify our callback to use the count state.

const ParentComponent = () => {
  const [count, setCount] = useState(0);

// This function now uses the 'count' state
  const handleButtonClick = useCallback(() => {
    alert(`The current count is: ${count}`);
  }, []); // <-- DANGER: Dependency array is empty!
  // ...
};

If you click “Re-render Parent” a few times to get the count to, say, 3, and then click the child's button, you'll get an alert saying “The current count is: 0”. This is a classic “stale closure.”

Our callback was created only once, when count was 0. It closed over that value and will remember it forever. It never gets the updated count.

The fix is to tell useCallback what it depends on.

const handleButtonClick = useCallback(() => {
  alert(`The current count is: ${count}`);
}, [count]); // <-- CORRECT: Now it depends on count

Now, React knows to give us a new function, but only if count changes. This fixes the stale closure but re-introduces a version of our original problem: a new function is created whenever the count changes, which will cause our memoized child to re-render.

The Pro Move: Using the State Updater Pattern

There’s a powerful pattern that lets us have the best of both worlds: useState's updater function pattern. setCount can take a function as an argument. React will pass the most up-to-date state to that function.

Let’s say our callback needed to increment the count.

// The dependent version (works, but creates new functions)
const increment = useCallback(() => {
  setCount(count + 1);
}, [count]);

// The independent, stable version
const incrementStable = useCallback(() => {
  setCount(prevCount => prevCount + 1);
}, []); // <-- The dependency array is EMPTY

By using the updater form setCount(prevCount => ...), our callback no longer needs to know what the current count is. It just needs the setCount function (which is guaranteed by React to be stable).

Now, our incrementStable function truly never changes, and we can pass it down to memoized children without breaking their optimization.

useCallback vs. useMemo:

useMemo, useCallback might seem familiar. In fact useCallback is just syntactic sugar for useMemo.

• useMemo(() => fn(), deps) invokes the function and memoizes its return value.
• useCallback(fn, deps) does not invoke the function. It memoizes the function itself.

In fact, These two lines are equivalent:

const fn1 = useCallback(myFunction, [a, b]);
const fn2 = useMemo(() => myFunction, [a, b]);

When Should You Use It?

useCallback is a performance optimization, but premature optimization is a trap. Don't wrap every function in useCallback. Use it when you have a specific reason.

1. Passing callbacks to optimized children: This is the primary use case. If you are passing a function to a component wrapped in React.memo, you should wrap that function in useCallback.
2. As a dependency for another hook: If a function is used inside a useEffect, useMemo, or another useCallback, it should be wrapped in useCallback to prevent the hook from re-running on every render.

The next time React.memo seems to be lying to you, you'll know exactly what to do. Happy Coding!

A Deep Dive into React’s useState Hook, From Basic Syntax to the Bugs That Bite You.

We’ve learnt React. We know what a component is. We’ve imported useState and made a counter. It went 0, 1, 2.

And then we tried to do something more complex.

We update an object, but the screen doesn’t change. Suddenly, our component isn’t re-rendering. If this sounds familiar, you’re not alone.

The useState hook is simple to learn but surprisingly easy to misuse. Let’s dissect this fundamental hook and fix the subtle bugs that drive us developers crazy. We’ll go from the absolute basics to the “Pro-League Hacks” that will make your state management bulletproof.

The useState 101

At its core, useState is a hook that adds a piece of memory (state) to a function component. When you call it, you give it an initial value, and it gives you back an array with two things:

1. The current state value (the “getter”).
2. A function to update that value (the “setter”).

We almost always use array destructuring to grab them.

import React, { useState } from 'react';

function Counter() {
  // 1. Call useState with an initial value (0)
  const [count, setCount] = useState<number>(0);
  const increment = () => {
    // 2. We call the setter with the new value
    setCount(count + 1);
  };
  return (
    <div>
      {/* 3. we use the getter to render the value */}
      <p>You clicked {count} times</p>
      <button onClick={increment}>
        Click me
      </button>
    </div>
  );
}

The first time this component appears, count is 0. When you click the “increment” button, the count updates. This update in the state causes the entire component to Re-render.

Mistake #1: Mutating object States

You must never, ever mutate object states directly.

React decides whether to re-render by checking if the state variable has changed. If your state is an object or an array (which is fundamentally an object in javascript), its “value” is actually a reference: an address in memory.

If you just change a property inside that object, the address stays the same. React looks at it, sees the same old address, and detects no change in the state, leading to no re-renders.

Updating Objects: Always use The Spread (...) Syntax

Let’s say we have a user state.

interface User {
  username: string;
  age: number;
}
const [user, setUser] = useState<User>({ username: 'alex', age: 25 });

The WRONG Way of Mutation: This code looks like it should work, but it won’t trigger a re-render.

const handleBirthday = () => {
  // We are changing the original 'user' object
  user.age = user.age + 1; 
  setUser(user); // React sees the same object reference! No update.
};

The RIGHT Way (Immutable Update): We create a brand new object by copying the old properties (...user) and then overwriting the one we want to change.

const handleBirthday = () => {
  // Create a new object with the copied properties and the new age
  setUser({ ...user, age: user.age + 1 });
};

Now, setUser is receiving a completely new object. React detects the change and re-renders your component.

Updating Arrays: .map() and .filter() are the best Tools

The same rule applies to arrays. You can’t use methods like .push() or .splice() because they mutate the original array.

Adding an Item Use the spread syntax to create a new array.

const [todos, setTodos] = useState<string[]>(['Learn React']);

const addTodo = () => {
  setTodos([...todos, 'Learn Hooks']); // Creates a new array
};

Removing an Item The .filter() method is perfect because it returns a brand new array.

const removeTodo = (todoToRemove: string) => {
  setTodos(todos.filter(todo => todo !== todoToRemove));
};

Updating an Item at an Index The .map() method is the go-to. It also returns a brand new array.

const updateTodo = (indexToUpdate: number, newValue: string) => {
  setTodos(todos.map((todo, index) => {
    return index === indexToUpdate ? newValue : todo;
  }));
};

Mistake #2: State Updates That Depend on Previous State

This is the subtle bug that separates the beginners from the pros. What happens when you want to update state multiple times in a single function?

Consider this component that tries to add 3 on a single click.

The Buggy Way

const handleClick = () => {
  setCount(count + 1); // If count is 0, this queues an update to 1
  setCount(count + 1); // 'count' is STILL 0, this queues an update to 1
  setCount(count + 1); // 'count' is STILL 0, this queues an update to 1
};
// Result: The count only goes up by 1.

Why does this fail? Because state is a snapshot. The count variable is a snapshot of the value from the last render. It doesn't change inside your handleClick function. React "batches" these calls, sees three requests to set the state to 1, and does it.

How does this Batching work?

When you call setState, the update doesn’t happen right away. Instead, React quietly collects all those updates into a little to-do list (“batch”).

Once the event handler (handleClick) is done running, React takes that list, figures out the final state (applying all the updates you made), and only then decides if it needs to re-render your component (if the new state is different from the old one).

This batching process is a big performance win. Without it, something like calling setCount(count + 1) three times would trigger three separate re-renders .

So React waits until your function finishes before applying all those updates at once.

The Safe Way: The Updater Function

To fix this, we pass a function to our setter. This updater function automatically receives the most recent, pending state from React’s Batch queue.

const handleClick = () => {
  // Pass a function to guarantee you're working with the latest state
  setCount(prevCount => prevCount + 1);
  setCount(prevCount => prevCount + 1);
  setCount(prevCount => prevCount + 1);
};
// Result: The count correctly goes up by 3!

React batches/queues these functions (instructions), not final values (or snapshots).

1. Instruction 1: “Take the current state (0) and add 1.” -> returns 1.
2. Instruction 2: “Take the current state ( now 1) and add 1.” -> returns 2.
3. Instruction 3: “Take the current state ( now 2) and add 1.” -> returns 3.

After your event handler finishes, React processes this queue and re-renders once with the final state of 3.

The rule is simple: If your new state depends on the previous state, always use the updater function form.

Conclusion

Mastering useStateis about understanding the principles:

1. State is Immutable: Never change objects or arrays directly. Always create a new one using spread syntax (...), .map(), or .filter().
2. State is a Snapshot: When a new state depends on the old one, don’t trust the state variable from the render. Use the updater function (setCount(prev => ...)) to get the latest value from React's queue.

Happy Coding!

If you’ve ever needed to “reach out and touch” a DOM element directly, or track a value between renders without causing an infinite loop, you’ve stumbled upon the exact problems that React’s useRef hook was designed to solve.

Think of useRef as creating a special "box" for a value. This box lives within your component and follows two very important rules:

1. The value inside the box persists for the entire lifetime of the component.
2. Changing the value inside the box does not cause the component to re-render.

Part 1: Accessing DOM Elements

The most common reason to reach for useRef is to get a direct "wire" to a specific element in the browser's DOM.

Let’s say we want to build an input field that is automatically focused as soon as the component loads. We need a way to tell the browser, “Hey, put the user’s cursor in that specific input.”

Here’s how we set it up.

Step 1: Declare the Ref

First, we import useRef and declare our ref inside the component.

import { useRef, useEffect } from 'react';

function AutoFocusInput() {
  const inputRef = useRef<HTMLInputElement>(null);
  // ... rest of the component
}

Let’s break it down:

• <HTMLInputElement>: This is a TypeScript generic. We are explicitly telling TypeScript, that The 'box' this ref creates is meant to hold an HTML input element.
• (null): We initialize the ref's value to null. This is mandatory for DOM refs. Because when this line of code first runs, the component hasn't rendered yet, so the <input> element doesn't exist in the DOM. The ref starts empty.

Step 2: Attach the Ref to the Element

Next, we use the special ref prop in our JSX (or TSX) to attach our inputRef to the <input> element.

<input ref={inputRef} type="text" placeholder="I will be focused" />

When React renders this JSX, it sees the ref prop and knows, when <input> in the actual DOM is created, that DOM node needs to place it inside the inputRef.current property.

Step 3: Use the Ref

The “box” that useRef creates is an object with a single, mutable property: .current. To access the DOM node, we use inputRef.current.

Since we want to focus the input right after it mounts, we use a useEffect hook with an empty dependency array.

import React, { useRef, useEffect } from 'react';

function AutoFocusInput() {
  const inputRef = useRef<HTMLInputElement>(null);
  useEffect(() => {
    
    inputRef.current?.focus();
  }, []); 
  
  // Empty array means this runs once, after the component mounts.
  return <input ref={inputRef} type="text" placeholder="I will be focused" />;
}

This flow is crucial:

1. During the initial render: inputRef.current is null.
2. After the component mounts: React updates inputRef.current to be the <input> DOM node.
3. useEffect runs: It can now safely access inputRef.current and call the browser's .focus() method on it.

Part 2: Holding Mutable Values

The second key job of useRef is storing any value that you want to change without causing a re-render. This is where it differs fundamentally from useState.

• setState(newValue) triggers a re-render.
• myRef.current = newValue does not trigger a re-render.

Let’s illustrate this with a classic problem: counting how many times a component renders. If we try to use useState, we create a disaster.

The Infinite Loop Problem with useState

import { useState, useEffect } from 'react';

function RenderCounter() {
  const [renderCount, setRenderCount] = useState(0);
  useEffect(() => {
    // This runs after every render
    setRenderCount(renderCount + 1);
  });
  return <div>I have rendered {renderCount} times.</div>;
}

This code creates an infinite loop. The component renders, useEffect runs, it updates the state with setRenderCount, which triggers a new render, which runs the useEffect again, and so on, forever.

The useRef Solution

This is the perfect scenario for useRef. Since updating a ref's .current property doesn't trigger a re-render, it breaks the loop.

import { useRef, useEffect } from 'react';

function RenderCounter() {
  // Create the ref "box", typed to hold a number
  const renderCountRef = useRef<number>(0);
  useEffect(() => {
    // Mutate the .current property. 
    // This does NOT trigger a re-render.
    renderCountRef.current = renderCountRef.current + 1;
  });
  return <div>I have rendered {renderCountRef.current} times.</div>;
}

The ref safely tracks the count across renders without causing more re-renders. So you can choose useRef or useState for a value, depending on whether the UI needs to re-render upon the value’s update.

Part 3: useRef’s TypeScript Syntax

With TypeScript, the syntax for useRef changes slightly depending on whether you're storing a value or referencing a DOM element.

Syntax for DOM Elements (like our <input>):

You provide the HTML element type and must initialize it with null.

// .current is of type: HTMLDivElement | null
const myDivRef = useRef<HTMLDivElement>(null);

If you forget to initialize it with null (useRef<HTMLInputElement>()), its .current property will be undefined. React's ref prop doesn't work with undefined, so your code won't connect the ref correctly. Always use null.

Syntax for Values (like our render counter):

You provide the type and a non-null starting value. TypeScript knows .current will always have that type.

// .current will ALWAYS be a number.
const countRef = useRef<number>(0);

// .current will be a number or null.
const intervalIdRef = useRef<number | null>(null);

Conclusion

useRef is a versatile and essential hook. By understanding its two primary use cases and the specific TypeScript patterns for each, you can write cleaner, more efficient, and bug-free React components.

Happy Coding!