# Async/await
Source: https://js.maxbraglia.com/async-apis/async-await

Write asynchronous code that reads like synchronous code

## The modern way to write async code

`async/await` is syntactic sugar on top of Promises. It lets you write async code that reads top-to-bottom, just like synchronous code. This is what you'll use 90% of the time.

```javascript theme={null}
async function getUsers() {
  const response = await fetch("http://localhost:8000/api/users");
  const users = await response.json();
  return users;
}
```

Two keywords, two rules:

* **`async`** goes before the function declaration — marks it as asynchronous
* **`await`** goes before a Promise — pauses execution until the Promise resolves

## async functions

Adding `async` to a function does one thing: it makes the function **always return a Promise**.

```javascript theme={null}
async function greet() {
  return "Hello!";
}

// Equivalent to:
function greet() {
  return Promise.resolve("Hello!");
}

// Both return a Promise
greet().then(message => console.log(message)); // "Hello!"
```

This means any function that uses `await` inside it must be marked `async`.

```javascript theme={null}
// ❌ Error: await is only valid in async functions
function getUsers() {
  const response = await fetch("/api/users"); // SyntaxError!
}

// ✅ Correct: mark function as async
async function getUsers() {
  const response = await fetch("/api/users");
  return response.json();
}
```

### Arrow function version

```javascript theme={null}
// Regular async function
async function getUsers() {
  const response = await fetch("/api/users");
  return response.json();
}

// Async arrow function
const getUsers = async () => {
  const response = await fetch("/api/users");
  return response.json();
};
```

## await — pausing until the Promise resolves

`await` pauses the function until the Promise settles. The function doesn't block the page — it just pauses internally while other code keeps running.

```javascript theme={null}
async function fetchAndLog() {
  console.log("1. Starting fetch...");

  const response = await fetch("/api/users"); // Pauses here
  console.log("2. Got response");              // Runs after fetch completes

  const users = await response.json();         // Pauses here
  console.log("3. Parsed JSON");               // Runs after parsing

  return users;
}

// Meanwhile, the rest of your app stays interactive
fetchAndLog();
console.log("4. This runs immediately — doesn't wait for fetchAndLog");

// Output:
// 1. Starting fetch...
// 4. This runs immediately — doesn't wait for fetchAndLog
// 2. Got response
// 3. Parsed JSON
```

<Warning>
  `await` pauses the current `async` function, not the entire program. Other code outside the function continues to run. That's why line 4 prints before lines 2 and 3.
</Warning>

## Error handling with try/catch

Use `try/catch` to handle errors in async functions — just like you would in Python:

```javascript theme={null}
async function getUsers() {
  try {
    const response = await fetch("http://localhost:8000/api/users");

    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }

    const users = await response.json();
    return users;
  } catch (error) {
    console.error("Failed to fetch users:", error.message);
    throw error; // Re-throw so the caller can handle it too
  }
}
```

`try/catch` catches both:

* **Network errors** — when `fetch` itself fails (no internet, DNS failure)
* **Errors you throw** — like when `response.ok` is false

### try/catch/finally

```javascript theme={null}
async function loadUsers() {
  setLoading(true);

  try {
    const response = await fetch("/api/users");
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const users = await response.json();
    setUsers(users);
  } catch (error) {
    setError(error.message);
  } finally {
    setLoading(false); // Always runs — success or failure
  }
}
```

<Tip>
  `finally` is perfect for resetting loading states. It runs regardless of success or failure, so you don't need to set `loading = false` in both the `try` and `catch` blocks.
</Tip>

## Sequential vs parallel

### Sequential — one after another

When each request depends on the previous result:

```javascript theme={null}
async function getUserOrders(userId) {
  const userResponse = await fetch(`/api/users/${userId}`);
  const user = await userResponse.json();

  // Need the user first to get their orders
  const ordersResponse = await fetch(`/api/orders?userId=${user.id}`);
  const orders = await ordersResponse.json();

  return { user, orders };
}
```

### Parallel — all at once

When requests are independent, use `Promise.all()` with `await`:

```javascript theme={null}
async function getDashboardData() {
  // ❌ Sequential — slow (each waits for the previous)
  const users = await fetch("/api/users").then(r => r.json());
  const products = await fetch("/api/products").then(r => r.json());
  const orders = await fetch("/api/orders").then(r => r.json());
  // Total time: request1 + request2 + request3

  // ✅ Parallel — fast (all run at the same time)
  const [users, products, orders] = await Promise.all([
    fetch("/api/users").then(r => r.json()),
    fetch("/api/products").then(r => r.json()),
    fetch("/api/orders").then(r => r.json()),
  ]);
  // Total time: max(request1, request2, request3)
}
```

<Warning>
  A common mistake is using `await` for every request even when they don't depend on each other. If two requests are independent, run them in parallel with `Promise.all()`.
</Warning>

## Comparing to Python

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    async function getUser(userId) {
      try {
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}`);
        }
        return await response.json();
      } catch (error) {
        console.error("Error:", error.message);
        throw error;
      }
    }

    // Call it
    const user = await getUser(1);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import httpx

    async def get_user(user_id: int):
        try:
            async with httpx.AsyncClient() as client:
                response = await client.get(f"/api/users/{user_id}")
                response.raise_for_status()
                return response.json()
        except httpx.HTTPError as error:
            print(f"Error: {error}")
            raise

    # Call it
    user = await get_user(1)
    ```
  </Tab>
</Tabs>

The syntax is nearly identical. The big difference: in Python, async is opt-in (most code is synchronous). In JavaScript, **any code that touches the network is async by default**.

## The pattern you'll use everywhere

This is the complete async/await pattern for API calls:

```javascript theme={null}
async function fetchData(endpoint) {
  try {
    const response = await fetch(`http://localhost:8000${endpoint}`);

    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error(`Failed to fetch ${endpoint}:`, error);
    throw error;
  }
}

// Usage
const users = await fetchData("/api/users");
const products = await fetchData("/api/products");
```

You'll see this exact pattern in nearly every web application. Learn it once, use it everywhere.

## What's next?

You understand async/await. Now let's put it to work — making real HTTP requests to your FastAPI backend with `fetch`.

<Card title="Fetching data from APIs" icon="cloud-arrow-down" href="/async-apis/fetch-basics">
  Make GET, POST, PUT, and DELETE requests with fetch
</Card>


# Callbacks
Source: https://js.maxbraglia.com/async-apis/callbacks

Understand the original async pattern in JavaScript and why we moved on

## What is a callback?

A callback is a function you pass to another function, to be called later when something finishes. You've already used them — `.map()`, `.filter()`, and `.forEach()` all take callbacks.

```javascript theme={null}
// You already know callbacks
const numbers = [1, 2, 3];
numbers.forEach(function(num) {  // This function is a callback
  console.log(num);
});

// Arrow function version (same thing)
numbers.forEach(num => console.log(num));
```

For async operations, callbacks work the same way: "When this async task finishes, call this function with the result."

```javascript theme={null}
// setTimeout uses a callback
console.log("Starting timer...");

setTimeout(() => {
  console.log("Timer finished!"); // Called after 2 seconds
}, 2000);

console.log("Timer is running in the background...");

// Output:
// Starting timer...
// Timer is running in the background...
// Timer finished!               ← 2 seconds later
```

## Callbacks for async operations

Before `fetch`, JavaScript used `XMLHttpRequest` with callbacks. Here's what async code looked like with callbacks:

```javascript theme={null}
// Simulating async API calls with callbacks
function getUser(userId, callback) {
  setTimeout(() => {
    const user = { id: userId, name: "Sarah Chen", role: "admin" };
    callback(user); // Call the callback with the result
  }, 1000);
}

// Usage
getUser(1, function(user) {
  console.log(user.name); // "Sarah Chen" — runs after 1 second
});
```

The pattern: pass a function that receives the result. The async operation calls your function when it's done.

## The error-first callback pattern

Node.js standardized a pattern: the first argument to a callback is always the error (or `null` if no error).

```javascript theme={null}
function getUser(userId, callback) {
  setTimeout(() => {
    if (userId <= 0) {
      callback(new Error("Invalid user ID"), null);
      return;
    }
    const user = { id: userId, name: "Sarah Chen" };
    callback(null, user); // null = no error
  }, 1000);
}

// Usage
getUser(1, function(error, user) {
  if (error) {
    console.error("Failed:", error.message);
    return;
  }
  console.log(user.name); // "Sarah Chen"
});
```

<Info>
  The error-first pattern (`callback(error, result)`) is a convention, not a language feature. Node.js APIs follow this pattern, but browser APIs like `fetch` use Promises instead.
</Info>

## Callback hell

The real problem shows up when you need multiple async operations that depend on each other — get a user, then get their orders, then get the order details:

```javascript theme={null}
// ❌ Callback hell — nested callbacks
getUser(1, function(error, user) {
  if (error) {
    console.error(error);
    return;
  }
  getOrders(user.id, function(error, orders) {
    if (error) {
      console.error(error);
      return;
    }
    getOrderDetails(orders[0].id, function(error, details) {
      if (error) {
        console.error(error);
        return;
      }
      console.log(details);
      // Need more? Keep nesting...
    });
  });
});
```

This is called **callback hell** or the "pyramid of doom." Every dependent async operation adds another level of nesting. It's:

* Hard to read
* Hard to debug
* Hard to handle errors properly
* Easy to make mistakes

Compare the same logic with the modern approach you'll learn soon:

```javascript theme={null}
// ✅ async/await — flat, readable
try {
  const user = await getUser(1);
  const orders = await getOrders(user.id);
  const details = await getOrderDetails(orders[0].id);
  console.log(details);
} catch (error) {
  console.error(error);
}
```

Same logic, no nesting, clean error handling. This is where we're headed.

## Where you'll still see callbacks

Callbacks aren't dead. You'll use them for:

```javascript theme={null}
// Event listeners
button.addEventListener("click", () => {
  console.log("Button clicked!");
});

// Array methods
const names = users.map(user => user.name);

// setTimeout / setInterval
setTimeout(() => {
  console.log("Delayed action");
}, 1000);
```

These are fine because they're not being nested. The problem was using callbacks for **sequential async operations**.

<Tip>
  You don't need to master callbacks for async work. The point of this lesson is to understand *why* Promises and async/await were created. For actual async code, you'll use async/await.
</Tip>

## What's next?

Promises were invented to solve callback hell. They give async operations a cleaner interface and let you chain operations without nesting.

<Card title="Promises" icon="handshake" href="/async-apis/promises">
  Handle async operations with a cleaner pattern
</Card>


# Error handling
Source: https://js.maxbraglia.com/async-apis/error-handling

Handle errors gracefully in your API calls and async code

## Why error handling matters

Network requests fail. Servers go down. Users lose internet. APIs return unexpected data. If you don't handle errors, your app shows a blank screen or crashes silently.

```javascript theme={null}
// ❌ No error handling — app crashes silently
async function getUsers() {
  const response = await fetch("/api/users");
  const users = await response.json();
  return users;
}

// ✅ With error handling — app stays usable
async function getUsers() {
  try {
    const response = await fetch("/api/users");
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    console.error("Failed to load users:", error);
    throw error;
  }
}
```

## try/catch/finally

The core pattern for handling errors in async code:

```javascript theme={null}
async function loadUserProfile(userId) {
  try {
    // Code that might fail
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const user = await response.json();
    return user;

  } catch (error) {
    // Runs if anything in try block throws
    console.error("Error loading profile:", error.message);
    return null; // Return a fallback value

  } finally {
    // Always runs — success or failure
    console.log("Request finished");
  }
}
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    try {
      const data = await riskyOperation();
    } catch (error) {
      console.error(error.message);
    } finally {
      cleanup();
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    try:
        data = await risky_operation()
    except Exception as error:
        print(error)
    finally:
        cleanup()
    ```
  </Tab>
</Tabs>

Same structure, same behavior. Python catches specific exception types; JavaScript catches everything in one `catch` block.

## Two types of fetch errors

This is where people get confused. `fetch` can fail in two different ways:

### 1. Network errors — fetch itself throws

```javascript theme={null}
try {
  // These throw immediately — no response at all
  const response = await fetch("/api/users");
} catch (error) {
  // TypeError: Failed to fetch
  // Causes: no internet, DNS failure, CORS blocked, server unreachable
  console.error("Network error:", error.message);
}
```

### 2. HTTP errors — fetch succeeds but status is bad

```javascript theme={null}
const response = await fetch("/api/users/999");

// fetch succeeded — we got a response
// But the status is 404 (not found)
console.log(response.ok);     // false
console.log(response.status); // 404

// We need to check manually and throw
if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
```

<Warning>
  `fetch` only throws on **network** failures. A 404 or 500 response is not an error from `fetch`'s perspective — it successfully received a response. Always check `response.ok`.
</Warning>

### Handling both types

```javascript theme={null}
async function getUsers() {
  try {
    const response = await fetch("/api/users");

    // Type 2: HTTP error (404, 500, etc.)
    if (!response.ok) {
      const errorBody = await response.json().catch(() => ({}));
      const error = new Error(errorBody.detail || `HTTP ${response.status}`);
      error.status = response.status; // Attach status for easier handling later
      throw error;
    }

    return await response.json();
  } catch (error) {
    // Type 1: Network error (no internet, CORS, etc.)
    // Type 2: HTTP error (thrown above)
    // Both are caught here
    console.error("Request failed:", error.message);
    throw error;
  }
}
```

## User-friendly error messages

Don't show raw error messages to users. Translate them into something helpful:

```javascript theme={null}
function getErrorMessage(error) {
  // Prefer structured data when available
  const status = error.status;

  // Network errors
  // Browser messages vary ("Failed to fetch", "NetworkError", etc.)
  if (!status && error.name === "TypeError") {
    return "Can't connect to the server. Check your internet connection.";
  }

  // HTTP errors
  if (status === 401 || error.message.includes("401")) {
    return "Please log in to continue.";
  }
  if (status === 403 || error.message.includes("403")) {
    return "You don't have permission to do that.";
  }
  if (status === 404 || error.message.includes("404")) {
    return "The item you're looking for doesn't exist.";
  }
  if (status === 500 || error.message.includes("500")) {
    return "Something went wrong on our end. Please try again.";
  }

  // Fallback
  return "Something went wrong. Please try again.";
}

// Usage
try {
  const users = await getUsers();
} catch (error) {
  showNotification(getErrorMessage(error)); // User sees a friendly message
}
```

### In React

```jsx theme={null}
function UserList() {
  const [users, setUsers] = useState([]);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadUsers() {
      try {
        const response = await fetch("/api/users");
        if (!response.ok) {
          const err = new Error(`HTTP ${response.status}`);
          err.status = response.status;
          throw err;
        }
        const data = await response.json();
        setUsers(data);
      } catch (error) {
        setError(getErrorMessage(error));
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []);

  if (loading) return <p>Loading...</p>;
  if (error) return <p className="error">{error}</p>;
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
```

## Re-throwing errors

Sometimes you want to handle an error *and* let the caller handle it too:

```javascript theme={null}
async function getUsers() {
  try {
    const response = await fetch("/api/users");
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    console.error("API error:", error); // Log it
    throw error; // Re-throw so the caller can handle it too
  }
}

// Caller handles the user-facing part
try {
  const users = await getUsers();
  renderUserList(users);
} catch (error) {
  showErrorBanner(getErrorMessage(error));
}
```

<Tip>
  Re-throw errors when lower-level code shouldn't decide what the user sees. Log the error for debugging, then throw it up to the component that can show a user-friendly message.
</Tip>

## Common mistakes

<AccordionGroup>
  <Accordion title="Swallowing errors silently">
    ```javascript theme={null}
    // ❌ Wrong: catching the error but doing nothing
    async function getUsers() {
      try {
        const response = await fetch("/api/users");
        return await response.json();
      } catch (error) {
        // Error is caught but nobody knows about it
        // App shows blank screen — no data, no error message
      }
    }

    // ✅ Correct: handle or re-throw
    async function getUsers() {
      try {
        const response = await fetch("/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
      } catch (error) {
        console.error("Failed:", error);
        throw error; // Let the caller handle it
      }
    }
    ```

    <Warning>
      An empty `catch` block is almost always a bug. If you catch an error, either handle it (show a message, return a fallback) or re-throw it. Silent failures are the hardest bugs to find.
    </Warning>
  </Accordion>

  <Accordion title="Not checking response.ok before parsing">
    ```javascript theme={null}
    // ❌ Wrong: parsing without checking status
    async function getUser(id) {
      const response = await fetch(`/api/users/${id}`);
      return response.json(); // Might parse a 404 error page as JSON
    }

    // ✅ Correct: check status first
    async function getUser(id) {
      const response = await fetch(`/api/users/${id}`);
      if (!response.ok) {
        const error = await response.json().catch(() => ({}));
        throw new Error(error.detail || `HTTP ${response.status}`);
      }
      return response.json();
    }
    ```
  </Accordion>

  <Accordion title="Using .catch() and try/catch together unnecessarily">
    ```javascript theme={null}
    // ❌ Confusing: mixing Promise .catch() with try/catch
    async function getUsers() {
      try {
        const response = await fetch("/api/users").catch(err => {
          throw err; // Unnecessary — try/catch already handles this
        });
        return response.json();
      } catch (error) {
        console.error(error);
      }
    }

    // ✅ Clean: just use try/catch with async/await
    async function getUsers() {
      try {
        const response = await fetch("/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        return await response.json();
      } catch (error) {
        console.error(error);
        throw error;
      }
    }
    ```

    <Warning>
      When using async/await, stick with `try/catch`. Don't mix in `.catch()` — it adds confusion without any benefit.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

Error handling keeps your app stable. Now let's make it feel fast with loading states — showing users what's happening while requests are in flight.

<Card title="Loading states" icon="spinner" href="/async-apis/loading-states">
  Show users what's happening during requests
</Card>


# Fetching data from APIs
Source: https://js.maxbraglia.com/async-apis/fetch-basics

Make HTTP requests to your FastAPI backend using fetch and async/await

## Making API calls

Every web app needs to communicate with a backend. JavaScript's `fetch()` function handles HTTP requests - GET to retrieve data, POST to create data, PUT to update, DELETE to remove.

You'll use this pattern in almost every React component that needs backend data.

## Basic GET request

```javascript theme={null}
async function getUsers() {
  const response = await fetch('http://localhost:8000/api/users');
  const data = await response.json();
  return data;
}

// Usage
const users = await getUsers();
console.log(users); // Array of user objects
```

`fetch()` returns a Promise, so you need `await`. The response needs to be converted to JSON with `.json()`.

<Info>
  The `.json()` method also returns a Promise, which is why it needs `await` too. It reads the response body and parses it as JSON.
</Info>

## Handling errors

```javascript theme={null}
async function getUsers() {
  try {
    const response = await fetch('http://localhost:8000/api/users');
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Failed to fetch users:', error);
    throw error; // Re-throw so caller can handle it
  }
}
```

Always check `response.ok` before parsing. A 404 or 500 status won't throw an error automatically - you have to check for it.

<Warning>
  `fetch()` only throws on network errors (no internet, DNS failure, etc.), not on HTTP error status codes. A 404 or 500 response is considered a "successful" fetch. Always check `response.ok`.
</Warning>

## POST request with data

```javascript theme={null}
async function createUser(userData) {
  const response = await fetch('http://localhost:8000/api/users', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(userData),
  });
  
  if (!response.ok) {
    throw new Error('Failed to create user');
  }
  
  return response.json();
}

// Usage
const newUser = await createUser({ 
  name: "John Doe", 
  email: "john@example.com" 
});
console.log(newUser); // { id: 1, name: "Sarah Doe", email: "sarah@example.com" }
```

POST requests need three things:

1. `method: 'POST'` - tells the server you're creating data
2. `headers` with `Content-Type: application/json` - tells the server you're sending JSON
3. `body` with `JSON.stringify()` - converts your JavaScript object to a JSON string

<Tip>
  Always use `JSON.stringify()` when sending data to an API. The body must be a string, not a JavaScript object.
</Tip>

## PUT and DELETE requests

```javascript theme={null}
// Update a user
async function updateUser(userId, updates) {
  const response = await fetch(`http://localhost:8000/api/users/${userId}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(updates),
  });
  
  if (!response.ok) throw new Error('Failed to update user');
  return response.json();
}

// Delete a user
async function deleteUser(userId) {
  const response = await fetch(`http://localhost:8000/api/users/${userId}`, {
    method: 'DELETE',
  });
  
  if (!response.ok) throw new Error('Failed to delete user');
  // DELETE often returns no content, so check first
  if (response.status === 204) return null;
  return response.json();
}
```

PUT and DELETE follow the same pattern. DELETE requests usually don't have a body, and often return status 204 (No Content) instead of JSON.

## Using environment variables

```javascript theme={null}
// ❌ Don't hardcode your API URL
const response = await fetch('http://localhost:8000/api/users');

// ✅ Use an environment variable
const API_URL = import.meta.env.VITE_API_URL;
const response = await fetch(`${API_URL}/api/users`);
```

Store your API URL in a `.env` file so you can change it between development and production without modifying code.

<Info>
  In Vite (the build tool we'll use), environment variables must start with `VITE_` to be exposed to your code. In your `.env` file: `VITE_API_URL=http://localhost:8000`
</Info>

## Complete example with error handling

```javascript api/users.js theme={null}
const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000';

export async function getUsers() {
  try {
    const response = await fetch(`${API_URL}/api/users`);
    if (!response.ok) {
      throw new Error(`Failed to fetch users: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    console.error('Error fetching users:', error);
    throw error;
  }
}

export async function createUser(userData) {
  try {
    const response = await fetch(`${API_URL}/api/users`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(userData),
    });
    
    if (!response.ok) {
      throw new Error(`Failed to create user: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Error creating user:', error);
    throw error;
  }
}

export async function updateUser(userId, updates) {
  try {
    const response = await fetch(`${API_URL}/api/users/${userId}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(updates),
    });
    
    if (!response.ok) {
      throw new Error(`Failed to update user: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Error updating user:', error);
    throw error;
  }
}

export async function deleteUser(userId) {
  try {
    const response = await fetch(`${API_URL}/api/users/${userId}`, {
      method: 'DELETE',
    });
    
    if (!response.ok) {
      throw new Error(`Failed to delete user: ${response.status}`);
    }
    
    if (response.status === 204) return null;
    return await response.json();
  } catch (error) {
    console.error('Error deleting user:', error);
    throw error;
  }
}
```

This is the pattern you'll use in every project - a separate file with all your API functions, proper error handling, and environment variables.

<Tip>
  Put all your API functions in a separate file (like `api/users.js`). This separates concerns and makes your code easier to test and maintain.
</Tip>

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting to await fetch">
    ```javascript theme={null}
    // ❌ Wrong: Missing await
    async function getUsers() {
      const data = fetch('http://localhost:8000/api/users');
      console.log(data); // Promise { <pending> }
      return data;
    }

    // ✅ Correct: Use await
    async function getUsers() {
      const response = await fetch('http://localhost:8000/api/users');
      const data = await response.json();
      return data;
    }
    ```

    <Warning>
      Without `await`, you get a Promise object, not the data. This is one of the most common async mistakes. Remember: `fetch()` returns a Promise, and so does `.json()`.
    </Warning>
  </Accordion>

  <Accordion title="Not checking response.ok">
    ```javascript theme={null}
    // ❌ Wrong: Assumes request succeeded
    async function getUsers() {
      const response = await fetch('http://localhost:8000/api/users');
      return response.json(); // Might fail on 404/500
    }

    // ✅ Correct: Check for errors
    async function getUsers() {
      const response = await fetch('http://localhost:8000/api/users');
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      return response.json();
    }
    ```

    <Warning>
      A 404 or 500 response won't throw an error automatically. Always check `response.ok` before calling `.json()`. Otherwise you might try to parse an error page as JSON and get confusing errors.
    </Warning>
  </Accordion>

  <Accordion title="Forgetting JSON.stringify for POST/PUT">
    ```javascript theme={null}
    // ❌ Wrong: Sending object directly
    const response = await fetch('http://localhost:8000/api/users', {
      method: 'POST',
      body: { name: "Sarah", email: "sarah@example.com" },
    });

    // ✅ Correct: Stringify the object
    const response = await fetch('http://localhost:8000/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: "Sarah", email: "sarah@example.com" }),
    });
    ```

    <Warning>
      The `body` must be a string, not a JavaScript object. Always use `JSON.stringify()`, and don't forget the `Content-Type` header.
    </Warning>
  </Accordion>

  <Accordion title="Not using try/catch">
    ```javascript theme={null}
    // ❌ Wrong: No error handling
    async function getUsers() {
      const response = await fetch('http://localhost:8000/api/users');
      return response.json();
    }

    // ✅ Correct: Wrap in try/catch
    async function getUsers() {
      try {
        const response = await fetch('http://localhost:8000/api/users');
        if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
        return await response.json();
      } catch (error) {
        console.error('Failed to fetch users:', error);
        throw error;
      }
    }
    ```

    <Warning>
      Network requests can fail for many reasons - no internet, server down, CORS errors. Always wrap fetch calls in try/catch so you can handle errors gracefully.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can now fetch data from your FastAPI backend. Next, let's learn how to work with the responses you get back — status codes, headers, and different response formats.

<Card title="Handling responses" icon="inbox" href="/async-apis/handling-responses">
  Parse API responses and work with different formats
</Card>


# Handling responses
Source: https://js.maxbraglia.com/async-apis/handling-responses

Parse API responses and work with different response formats

## The Response object

When `fetch` completes, you get a `Response` object. It's not the data itself — it's a wrapper with metadata about the response and methods to extract the body.

```javascript theme={null}
const response = await fetch("http://localhost:8000/api/users");

console.log(response.status);     // 200
console.log(response.ok);         // true (status 200-299)
console.log(response.statusText); // "OK"
console.log(response.headers);    // Headers object
console.log(response.url);        // "http://localhost:8000/api/users"
```

## Key response properties

| Property              | Type    | Description                            |
| --------------------- | ------- | -------------------------------------- |
| `response.ok`         | boolean | `true` if status is 200–299            |
| `response.status`     | number  | HTTP status code (200, 404, 500, etc.) |
| `response.statusText` | string  | Status text ("OK", "Not Found", etc.)  |
| `response.headers`    | Headers | Response headers                       |
| `response.url`        | string  | The URL that was fetched               |

### Status codes you'll see most often

```javascript theme={null}
const response = await fetch("/api/users");

switch (response.status) {
  case 200: // OK — data returned
    return await response.json();
  case 201: // Created — new resource created (after POST)
    return await response.json();
  case 204: // No Content — success but no body (after DELETE)
    return null;
  case 400: // Bad Request — invalid data sent
    throw new Error("Invalid request data");
  case 401: // Unauthorized — not logged in
    throw new Error("Please log in");
  case 403: // Forbidden — logged in but not allowed
    throw new Error("Access denied");
  case 404: // Not Found — resource doesn't exist
    throw new Error("Resource not found");
  case 500: // Internal Server Error — server broke
    throw new Error("Server error");
}
```

<Tip>
  You don't need to memorize all status codes. The important ones: **200** (success), **201** (created), **204** (no content), **400** (bad request), **401** (unauthorized), **404** (not found), **500** (server error).
</Tip>

## Checking response.ok

The most important property. It's `true` for any 2xx status code:

```javascript theme={null}
async function getUsers() {
  const response = await fetch("/api/users");

  if (!response.ok) {
    // Status is 400, 401, 403, 404, 500, etc.
    throw new Error(`HTTP error: ${response.status}`);
  }

  // Status is 200, 201, etc.
  return response.json();
}
```

<Warning>
  `fetch` does **not** throw an error for 404 or 500 responses. It only throws on network failures (no internet, DNS error). You must check `response.ok` yourself. This is the most common source of bugs in fetch code.
</Warning>

## Extracting the response body

The Response object has methods to read the body in different formats:

```javascript theme={null}
const response = await fetch("/api/users");

// Most common — parse as JSON
const data = await response.json();

// Plain text
const text = await response.text();

// Binary data (images, files)
const blob = await response.blob();

// Form data
const formData = await response.formData();
```

<Warning>
  You can only read the body **once**. After calling `.json()`, you can't call `.text()` on the same response. If you need the body in multiple formats, use `.text()` first and parse manually.
</Warning>

### .json() — the one you'll use 90% of the time

```javascript theme={null}
async function getUsers() {
  const response = await fetch("http://localhost:8000/api/users");

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const users = await response.json(); // Parse JSON body into a JS object/array
  return users;
}

const users = await getUsers();
console.log(users); // [{ id: 1, name: "Sarah Chen" }, ...]
```

Remember: `.json()` returns a Promise, so you need `await`. It calls `JSON.parse()` internally.

## Reading response headers

```javascript theme={null}
const response = await fetch("/api/users");

// Get a specific header
const contentType = response.headers.get("Content-Type");
console.log(contentType); // "application/json"

// Check total count (if your API sends it)
const totalCount = response.headers.get("X-Total-Count");
console.log(totalCount); // "42"

// Iterate all headers
response.headers.forEach((value, name) => {
  console.log(`${name}: ${value}`);
});
```

<Info>
  FastAPI and other backends can send custom headers like `X-Total-Count` for pagination. Access them with `response.headers.get("Header-Name")`.
</Info>

## Handling different response shapes

Your FastAPI backend might return data in different structures. Handle them appropriately:

```javascript theme={null}
// Single object
const response = await fetch("/api/users/1");
const user = await response.json();
// { id: 1, name: "Sarah Chen", email: "sarah@example.com" }

// Array
const response = await fetch("/api/users");
const users = await response.json();
// [{ id: 1, name: "Sarah Chen" }, { id: 2, name: "John Park" }]

// Paginated response
const response = await fetch("/api/users?page=1&limit=10");
const result = await response.json();
// { data: [...], total: 42, page: 1, pages: 5 }
const { data: users, total, pages } = result;

// Empty response (204 No Content)
const response = await fetch("/api/users/1", { method: "DELETE" });
if (response.status === 204) {
  console.log("Deleted successfully — no body to parse");
}
```

### Handling error responses from your API

FastAPI returns structured error responses. Parse them to show useful messages:

```javascript theme={null}
async function createUser(userData) {
  const response = await fetch("/api/users", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(userData),
  });

  if (!response.ok) {
    // FastAPI returns { "detail": "Error message" }
    const errorBody = await response.json();
    throw new Error(errorBody.detail || `HTTP ${response.status}`);
  }

  return response.json();
}

// Usage
try {
  await createUser({ name: "" }); // Invalid data
} catch (error) {
  console.log(error.message); // "Name is required" (from FastAPI)
}
```

<Tip>
  Don't just throw generic "request failed" errors. Parse the error response body — your FastAPI backend sends useful validation messages. Show those to your users.
</Tip>

## Complete pattern

Here's how all of this comes together in a real API function:

```javascript theme={null}
async function apiRequest(endpoint, options = {}) {
  const response = await fetch(`http://localhost:8000${endpoint}`, options);

  // Handle no-content responses
  if (response.status === 204) {
    return null;
  }

  // Parse the body (whether success or error)
  const body = await response.json();

  // Throw with the server's error message
  if (!response.ok) {
    throw new Error(body.detail || `HTTP ${response.status}`);
  }

  return body;
}

// Usage
const users = await apiRequest("/api/users");
const newUser = await apiRequest("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Sarah Chen", email: "sarah@example.com" }),
});
```

## What's next?

You know how to read responses. But what happens when things go wrong? Let's learn how to handle errors gracefully.

<Card title="Error handling" icon="triangle-exclamation" href="/async-apis/error-handling">
  Handle errors in your API calls and async code
</Card>


# Loading states
Source: https://js.maxbraglia.com/async-apis/loading-states

Show users what's happening while data is being fetched

## Why loading states matter

When your app fetches data, there's a gap between clicking and seeing results. Without a loading state, users see either nothing (blank screen) or stale data. They don't know if the app is working.

```jsx theme={null}
// ❌ No loading state — user sees blank page for 1-3 seconds
function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch("/api/users")
      .then(r => r.json())
      .then(data => setUsers(data));
  }, []);

  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
  // Empty list until data arrives — looks broken
}
```

## The loading state pattern

Every data-fetching component needs three states: **loading**, **error**, and **data**.

```jsx theme={null}
function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUsers() {
      try {
        setLoading(true);
        const response = await fetch("/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const data = await response.json();
        setUsers(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []);

  if (loading) return <p>Loading users...</p>;
  if (error) return <p>Error: {error}</p>;
  if (users.length === 0) return <p>No users found.</p>;

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

This is the pattern you'll use in almost every component that fetches data. Three states, three checks at the top of the return.

<Info>
  Notice the order: check `loading` first, then `error`, then empty state, then render data. This order matters because you want to show the most relevant state.
</Info>

## Loading indicators

### Simple text

```jsx theme={null}
if (loading) return <p>Loading...</p>;
```

### Spinner component

```jsx theme={null}
function Spinner() {
  return <div className="spinner" aria-label="Loading" />;
}

// Usage
if (loading) return <Spinner />;
```

```css theme={null}
.spinner {
  width: 24px;
  height: 24px;
  border: 3px solid #e5e7eb;
  border-top-color: #3b82f6;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}
```

### Inline loading (inside existing content)

```jsx theme={null}
function UserList() {
  // ...state setup

  return (
    <div>
      <h2>Users {loading && <Spinner />}</h2>
      {error && <p className="error">{error}</p>}
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

<Tip>
  Use full-page loading for initial loads and inline loading for refreshes. If the user already sees data, don't replace it with a spinner — show the spinner alongside the existing content.
</Tip>

## Disabling buttons during requests

Prevent users from double-clicking submit buttons:

```jsx theme={null}
function CreateUserForm() {
  const [name, setName] = useState("");
  const [submitting, setSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault();
    setSubmitting(true);

    try {
      const response = await fetch("/api/users", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name }),
      });

      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const newUser = await response.json();
      console.log("Created:", newUser);
    } catch (error) {
      console.error("Failed:", error);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={name}
        onChange={e => setName(e.target.value)}
        disabled={submitting}
      />
      <button type="submit" disabled={submitting}>
        {submitting ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}
```

Key details:

* `disabled={submitting}` prevents the button from being clicked again
* Button text changes to show progress ("Creating...")
* Input is also disabled to prevent editing during submission
* `finally` ensures the button re-enables even if the request fails

<Warning>
  Always disable submit buttons during requests. Without this, users can click multiple times and create duplicate entries. This is one of the most common bugs in web applications.
</Warning>

## The complete data fetching pattern

This is the pattern you'll reuse across your entire application:

```jsx theme={null}
function DataComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchData() {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch("/api/endpoint");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const result = await response.json();
        setData(result);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchData();
  }, []);

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!data) return <EmptyState />;

  return <DataDisplay data={data} />;
}
```

<Tip>
  This three-state pattern (loading / error / data) shows up so often that libraries like React Query and SWR were created to automate it. For now, writing it manually teaches you what's happening under the hood.
</Tip>

## Refactoring into a custom hook

Once you're comfortable with the pattern, extract it into a reusable hook:

```jsx theme={null}
function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchData() {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch(url);
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        setData(await response.json());
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    fetchData();
  }, [url]);

  return { data, loading, error };
}

// Usage — so clean!
function UserList() {
  const { data: users, loading, error } = useFetch("/api/users");

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

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

One hook, any endpoint. The same loading/error/data pattern without repeating yourself.

## What's next?

You've covered the complete async & APIs section — from understanding async JavaScript to making real API calls with proper error handling and loading states.

Next up: the DOM and browser APIs. You'll learn how JavaScript interacts with the page itself — selecting elements, modifying content, and responding to user actions.

<Card title="What is the DOM?" icon="sitemap" href="/dom-browser/what-is-dom">
  Understand how JavaScript sees and interacts with your page
</Card>


# Promises
Source: https://js.maxbraglia.com/async-apis/promises

Handle async operations with JavaScript Promises

## What is a Promise?

A Promise is an object that represents the eventual result of an async operation. Instead of passing a callback, the async function returns a Promise — a container that will eventually hold the result (or an error).

```javascript theme={null}
const promise = fetch("http://localhost:8000/api/users");

console.log(promise); // Promise { <pending> }
// The data isn't here yet, but the Promise will deliver it when it arrives
```

A Promise has three states:

| State         | Meaning                                             |
| ------------- | --------------------------------------------------- |
| **Pending**   | The operation is still running                      |
| **Fulfilled** | The operation completed successfully (has a result) |
| **Rejected**  | The operation failed (has an error)                 |

<Info>
  Think of a Promise like a food delivery order. It starts as "pending" (being prepared). It either gets "fulfilled" (delivered successfully) or "rejected" (restaurant cancelled the order). You can't change the outcome once it's settled.
</Info>

## .then() — handling the result

Use `.then()` to specify what happens when the Promise fulfills:

```javascript theme={null}
fetch("http://localhost:8000/api/users")
  .then(response => {
    console.log("Got response:", response.status);
    return response.json(); // This also returns a Promise
  })
  .then(users => {
    console.log("Users:", users);
  });
```

`.then()` takes a function that receives the result. It also **returns a new Promise**, which is what enables chaining.

### Chaining Promises

This is the key advantage over callbacks — sequential async operations stay flat:

```javascript theme={null}
// Chained .then() calls — no nesting
fetch("http://localhost:8000/api/users/1")
  .then(response => response.json())
  .then(user => fetch(`http://localhost:8000/api/orders?userId=${user.id}`))
  .then(response => response.json())
  .then(orders => {
    console.log("User orders:", orders);
  });
```

Compare this to the nested callback version:

```javascript theme={null}
// Callbacks — pyramid of doom
getUser(1, (err, user) => {
  getOrders(user.id, (err, orders) => {
    console.log("User orders:", orders);
  });
});
```

Each `.then()` returns a new Promise, so you can keep chaining. The data flows from one `.then()` to the next.

## .catch() — handling errors

Use `.catch()` to handle errors anywhere in the chain:

```javascript theme={null}
fetch("http://localhost:8000/api/users")
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`);
    }
    return response.json();
  })
  .then(users => {
    console.log(users);
  })
  .catch(error => {
    console.error("Something failed:", error.message);
  });
```

A single `.catch()` at the end handles errors from **any step** in the chain. If `fetch()` fails, or `response.ok` is false, or `.json()` fails — the error flows down to `.catch()`.

<Warning>
  Always add `.catch()` at the end of a Promise chain. Without it, errors are silently swallowed. You'll see "Uncaught (in promise)" warnings in the console, but your code won't handle them.
</Warning>

## .finally() — cleanup code

`.finally()` runs regardless of success or failure. Use it for cleanup:

```javascript theme={null}
showSpinner();

fetch("http://localhost:8000/api/users")
  .then(response => response.json())
  .then(users => renderUserList(users))
  .catch(error => showErrorMessage(error))
  .finally(() => {
    hideSpinner(); // Runs whether request succeeded or failed
  });
```

## Promise.all() — multiple requests in parallel

When you need data from multiple endpoints and they don't depend on each other, run them in parallel:

```javascript theme={null}
const [users, products, orders] = await Promise.all([
  fetch("http://localhost:8000/api/users").then(r => r.json()),
  fetch("http://localhost:8000/api/products").then(r => r.json()),
  fetch("http://localhost:8000/api/orders").then(r => r.json()),
]);

console.log(users, products, orders); // All three results
```

`Promise.all()` takes an array of Promises and returns a single Promise that resolves when **all** of them complete. If any one fails, the whole thing rejects.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const [users, posts] = await Promise.all([
      fetch("/api/users").then(r => r.json()),
      fetch("/api/posts").then(r => r.json()),
    ]);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import asyncio

    users, posts = await asyncio.gather(
        fetch_users(),
        fetch_posts(),
    )
    ```
  </Tab>
</Tabs>

JavaScript's `Promise.all()` is like Python's `asyncio.gather()`. Same concept — run multiple async operations concurrently.

## Creating your own Promises

You'll rarely need to create Promises from scratch, but here's how:

```javascript theme={null}
function delay(ms) {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
}

// Usage
await delay(2000); // Wait 2 seconds
console.log("Done waiting!");
```

The `new Promise()` constructor takes a function with two parameters:

* `resolve(value)` — call when the operation succeeds
* `reject(error)` — call when the operation fails

```javascript theme={null}
function fetchWithTimeout(url, ms) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      reject(new Error("Request timed out"));
    }, ms);

    fetch(url)
      .then(response => {
        clearTimeout(timer);
        resolve(response);
      })
      .catch(error => {
        clearTimeout(timer);
        reject(error);
      });
  });
}
```

<Tip>
  Most of the time, you'll *consume* Promises (from `fetch`, libraries, etc.), not create them. Focus on understanding `.then()`, `.catch()`, and `Promise.all()`.
</Tip>

## Why you'll use async/await instead

Promises solved callback hell, but chaining `.then()` calls can still get verbose. The next step — async/await — lets you write the same async code in a way that reads like synchronous code:

```javascript theme={null}
// Promise chain
fetch("/api/users")
  .then(response => response.json())
  .then(users => console.log(users))
  .catch(error => console.error(error));

// async/await — same thing, cleaner
try {
  const response = await fetch("/api/users");
  const users = await response.json();
  console.log(users);
} catch (error) {
  console.error(error);
}
```

async/await is built on top of Promises — it's syntactic sugar, not a replacement. Understanding Promises helps you understand what async/await is doing under the hood.

## What's next?

Time to learn async/await — the modern syntax you'll use 90% of the time for async operations.

<Card title="Async/await" icon="code" href="/async-apis/async-await">
  Write async code that reads like synchronous code
</Card>


# Why async matters
Source: https://js.maxbraglia.com/async-apis/why-async-matters

Understand why JavaScript handles tasks asynchronously and what that means for your code

## The problem with waiting

In Python, code runs line by line. Each line finishes before the next one starts. When you call `requests.get()`, your program stops and waits until the response comes back.

```python theme={null}
# Python — synchronous (blocking)
import requests

print("Fetching users...")
response = requests.get("http://localhost:8000/api/users")  # Program stops here
users = response.json()                                      # Waits until above finishes
print(f"Got {len(users)} users")                            # Then continues
```

This works fine for a script. But in a browser, **blocking means the entire page freezes**. No scrolling, no clicking, no animations — nothing until the request finishes. That's a terrible user experience.

## JavaScript is single-threaded

JavaScript runs on a single thread — one line of code at a time. If a network request takes 3 seconds and JavaScript just waited, your entire page would be frozen for 3 seconds.

```javascript theme={null}
// ❌ If JavaScript worked synchronously (it doesn't)
console.log("Fetching users...");
const response = fetch("http://localhost:8000/api/users"); // Imagine this blocks for 3 seconds
const users = response.json();                              // Page frozen the whole time
console.log(`Got ${users.length} users`);
```

JavaScript solves this with **asynchronous execution**. Instead of waiting for slow operations, JavaScript says "start this task, and I'll come back to it when it's done." Meanwhile, the page stays interactive.

## How async actually works

Think of it like ordering at a restaurant:

**Synchronous (Python script)**: You order food, stand at the counter staring at the kitchen, and don't do anything else until your food arrives.

**Asynchronous (JavaScript)**: You order food, get a **ticket number** (a Promise), and sit down. You can check your phone, talk to friends — the restaurant will call your number when the food is ready.

```javascript theme={null}
// JavaScript — asynchronous (non-blocking)
console.log("1. Fetching users...");

fetch("http://localhost:8000/api/users")
  .then(response => response.json())
  .then(users => {
    console.log(`3. Got ${users.length} users`);
  });

console.log("2. This runs while waiting!");
```

Output:

```
1. Fetching users...
2. This runs while waiting!
3. Got 5 users           ← arrives later
```

<Warning>
  Notice the order: line "2" runs before line "3" even though it comes after the fetch in the code. This is the fundamental concept of async JavaScript. Code doesn't necessarily run in the order it appears.
</Warning>

## The event loop (simplified)

You don't need to understand every detail of the event loop, but here's the key idea:

1. JavaScript runs your code line by line on the **main thread**
2. When it hits an async operation (network request, timer, etc.), it hands it off to the browser
3. The browser handles the operation in the background
4. When the operation completes, the result goes into a **queue**
5. JavaScript picks up results from the queue when it's done with the current code

```javascript theme={null}
console.log("Start");

setTimeout(() => {
  console.log("Timer done"); // Runs after current code finishes
}, 0); // Even with 0ms delay!

console.log("End");

// Output:
// Start
// End
// Timer done   ← even 0ms setTimeout runs after current code
```

<Info>
  `setTimeout` with `0` milliseconds doesn't run immediately — it runs after the current code finishes. This proves that async callbacks always wait for the main thread to be free.
</Info>

## What operations are async?

Not everything in JavaScript is async. Only operations that take an unpredictable amount of time:

| Async (takes time)               | Sync (instant)                        |
| -------------------------------- | ------------------------------------- |
| `fetch()` — network requests     | Math operations                       |
| `setTimeout()` / `setInterval()` | String manipulation                   |
| Reading files (in Node.js)       | Array methods (`.map()`, `.filter()`) |
| Database queries                 | Object operations                     |
| User input events                | Variable assignment                   |

In web development, the most common async operation is **fetching data from your backend**.

## Why this matters for you

As a Python developer, async is the biggest mental shift. In Python, you can mostly ignore async unless you're using `asyncio`. In JavaScript, **you'll deal with async in almost every component** that fetches data.

The good news: JavaScript has clean syntax for handling async code. Over the next few lessons, you'll learn the evolution:

1. **Callbacks** — the original approach (messy)
2. **Promises** — a better abstraction (cleaner)
3. **async/await** — modern syntax (cleanest, what you'll actually use)

<Tip>
  Don't try to fight async or make everything synchronous. Embrace it. Once you understand the pattern, it becomes second nature — and it's what makes web apps feel fast and responsive.
</Tip>

## What's next?

Let's start with the original async pattern — callbacks. Understanding callbacks helps you appreciate why Promises and async/await exist.

<Card title="Callbacks" icon="phone-arrow-right" href="/async-apis/callbacks">
  The original async pattern and why we moved on
</Card>


# Creating elements
Source: https://js.maxbraglia.com/dom-browser/creating-elements

Dynamically add new HTML elements to the page with JavaScript

## Building the page with JavaScript

So far you've modified existing elements. But often you need to create new ones — render a list of users from an API, add a notification, or build a table from data. This is where `document.createElement()` comes in.

## document.createElement()

Create a new element, configure it, then add it to the page:

```javascript theme={null}
// 1. Create the element
const card = document.createElement("div");

// 2. Configure it
card.className = "user-card";
card.textContent = "Sarah Chen — Admin";

// 3. Add it to the page
document.querySelector("#user-list").appendChild(card);
```

The element doesn't appear on the page until you add it to the DOM with `appendChild` or similar methods.

### A more complete example

```javascript theme={null}
// Create a user card with multiple child elements
const card = document.createElement("div");
card.className = "user-card";

const name = document.createElement("h3");
name.textContent = "Sarah Chen";

const email = document.createElement("p");
email.textContent = "sarah@example.com";
email.className = "email";

const deleteBtn = document.createElement("button");
deleteBtn.textContent = "Delete";
deleteBtn.className = "btn-danger";

// Build the tree
card.appendChild(name);
card.appendChild(email);
card.appendChild(deleteBtn);

// Add to the page
document.querySelector("#user-list").appendChild(card);
```

This produces:

```html theme={null}
<div class="user-card">
  <h3>Sarah Chen</h3>
  <p class="email">sarah@example.com</p>
  <button class="btn-danger">Delete</button>
</div>
```

## Adding elements to the page

Several methods for inserting elements, each with a different position:

```javascript theme={null}
const parent = document.querySelector("#container");
const newElement = document.createElement("p");
newElement.textContent = "New paragraph";

// Add to the end (most common)
parent.appendChild(newElement);

// Add to the beginning
parent.prepend(newElement);

// Add to the end (modern alternative to appendChild)
parent.append(newElement);

// Insert before a specific child
const reference = document.querySelector("#reference-element");
parent.insertBefore(newElement, reference);

// Insert relative to an element
reference.before(newElement);   // Before the reference
reference.after(newElement);    // After the reference
```

| Method                   | Position        | Returns              |
| ------------------------ | --------------- | -------------------- |
| `parent.appendChild(el)` | End of parent   | The appended element |
| `parent.append(el)`      | End of parent   | `undefined`          |
| `parent.prepend(el)`     | Start of parent | `undefined`          |
| `el.before(newEl)`       | Before `el`     | `undefined`          |
| `el.after(newEl)`        | After `el`      | `undefined`          |

<Tip>
  `append()` and `prepend()` are the modern alternatives. They also accept strings: `parent.append("Hello")` adds a text node. `appendChild` only accepts elements.
</Tip>

## Removing elements

```javascript theme={null}
// Modern — call .remove() on the element
const card = document.querySelector(".user-card");
card.remove();

// Older — remove through parent
const parent = card.parentElement;
parent.removeChild(card);

// Remove all children
const container = document.querySelector("#container");
container.innerHTML = ""; // Quick way to clear everything
```

## Rendering a list from data

This is the most common use case — take data (from an API, for example) and build the DOM:

```javascript theme={null}
const users = [
  { id: 1, name: "Sarah Chen", role: "Admin" },
  { id: 2, name: "John Park", role: "Editor" },
  { id: 3, name: "Alice Rivera", role: "Viewer" },
];

const list = document.querySelector("#user-list");

users.forEach(user => {
  const li = document.createElement("li");
  li.textContent = `${user.name} — ${user.role}`;
  li.dataset.userId = user.id;
  list.appendChild(li);
});
```

### With innerHTML (simpler for complex HTML)

```javascript theme={null}
const users = [
  { id: 1, name: "Sarah Chen", role: "Admin" },
  { id: 2, name: "John Park", role: "Editor" },
  { id: 3, name: "Alice Rivera", role: "Viewer" },
];

const list = document.querySelector("#user-list");

list.innerHTML = users.map(user => `
  <li data-user-id="${user.id}">
    <strong>${user.name}</strong>
    <span class="role">${user.role}</span>
  </li>
`).join("");
```

<Warning>
  `innerHTML` with template literals is convenient but vulnerable to XSS if the data contains user input. For data from your own API, it's fine. For user-generated content, use `createElement` + `textContent`.
</Warning>

## Document fragments (batch insertions)

When adding many elements, each `appendChild` triggers a page repaint. Use a `DocumentFragment` to batch insertions:

```javascript theme={null}
const users = await fetch("/api/users").then(r => r.json());
const fragment = document.createDocumentFragment();

users.forEach(user => {
  const li = document.createElement("li");
  li.textContent = user.name;
  fragment.appendChild(li); // Add to fragment (no repaint)
});

document.querySelector("#user-list").appendChild(fragment);
// Single repaint when the fragment is added to the DOM
```

<Info>
  For small lists (under 100 items), the performance difference is negligible. Use fragments when rendering large datasets or when you notice visible flickering during rendering.
</Info>

## How React replaces this

Everything in this lesson — `createElement`, `appendChild`, `innerHTML` — is what React automates. Compare:

```javascript theme={null}
// Vanilla JavaScript
const users = [{ name: "Sarah" }, { name: "John" }];
const list = document.querySelector("#user-list");
list.innerHTML = users.map(u => `<li>${u.name}</li>`).join("");
```

```jsx theme={null}
// React — same result, declarative approach
function UserList({ users }) {
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

React handles creating, updating, and removing DOM elements for you. You describe *what* the UI should look like; React figures out *how* to make it happen.

<Tip>
  Understanding `createElement` helps you appreciate what React does under the hood. You won't use manual DOM creation in React projects, but you'll understand error messages and debugging better.
</Tip>

## What's next?

You can create and add elements to the page. Now let's make them interactive — responding to clicks, typing, and other user actions.

<Card title="Event listeners" icon="bell" href="/dom-browser/event-listeners">
  Respond to user interactions like clicks and keyboard input
</Card>


# Browser DevTools
Source: https://js.maxbraglia.com/dom-browser/dev-tools

Use browser developer tools to inspect, debug, and test your JavaScript

## Your most important tool

Browser DevTools is where you'll spend a significant chunk of your development time. It lets you inspect the DOM, run JavaScript, monitor network requests, and debug errors — all without leaving the browser.

### Opening DevTools

<Tabs>
  <Tab title="Chrome / Edge">
    | Action                | Shortcut                                                 |
    | --------------------- | -------------------------------------------------------- |
    | Open DevTools         | `F12` or `Ctrl+Shift+I` (Windows) / `Cmd+Option+I` (Mac) |
    | Open Console directly | `Ctrl+Shift+J` (Windows) / `Cmd+Option+J` (Mac)          |
    | Inspect element       | `Ctrl+Shift+C` (Windows) / `Cmd+Option+C` (Mac)          |
  </Tab>

  <Tab title="Firefox">
    | Action                | Shortcut                                                 |
    | --------------------- | -------------------------------------------------------- |
    | Open DevTools         | `F12` or `Ctrl+Shift+I` (Windows) / `Cmd+Option+I` (Mac) |
    | Open Console directly | `Ctrl+Shift+K` (Windows) / `Cmd+Option+K` (Mac)          |
    | Inspect element       | `Ctrl+Shift+C` (Windows) / `Cmd+Option+C` (Mac)          |
  </Tab>

  <Tab title="Safari">
    | Action                | Shortcut       |
    | --------------------- | -------------- |
    | Open DevTools         | `Cmd+Option+I` |
    | Open Console directly | `Cmd+Option+C` |

    Enable DevTools first: Safari → Settings → Advanced → "Show features for web developers"
  </Tab>
</Tabs>

<Tip>
  Right-click any element on a page and select **"Inspect"** to jump directly to that element in the Elements panel. This is the fastest way to investigate any part of a page.
</Tip>

## Elements panel

The Elements panel shows the live DOM tree. You can inspect, edit, and experiment with any element on the page.

### What you can do

```
Elements panel lets you:
├── See the full DOM tree (expand/collapse nodes)
├── Click an element to see its styles in the Styles pane
├── Edit HTML directly (double-click any element)
├── Edit CSS in real time (change values, add properties)
├── Toggle classes on and off
├── See computed styles (what the browser actually applied)
└── Check element box model (margin, padding, border)
```

### Practical uses

* **Debug layout issues**: Inspect an element, check its computed size, margin, and padding
* **Test style changes**: Edit CSS values live — no need to save and reload
* **Find elements**: Use `Ctrl+F` / `Cmd+F` in the Elements panel to search by text, selector, or XPath
* **Check accessibility**: See element roles, ARIA attributes, and contrast ratios

<Info>
  Changes you make in the Elements panel are temporary — they disappear when you refresh the page. This makes it safe to experiment without fear of breaking anything.
</Info>

## Console panel

The Console is where you'll run JavaScript interactively, see errors, and debug your code.

### Running JavaScript

```javascript theme={null}
// Type these directly in the console

// Access DOM elements
document.querySelector("h1").textContent
// "Hello, Sarah!"

// Change the page
document.body.style.backgroundColor = "lightblue"

// Test your functions
const numbers = [1, 2, 3, 4, 5];
numbers.filter(n => n > 3);
// [4, 5]

// Inspect objects
console.log({ name: "Sarah", age: 28 });
console.table([{ id: 1, name: "Sarah" }, { id: 2, name: "John" }]);
```

### Console methods

| Method                                   | Purpose                           |
| ---------------------------------------- | --------------------------------- |
| `console.log()`                          | General output                    |
| `console.error()`                        | Red error message                 |
| `console.warn()`                         | Yellow warning                    |
| `console.table()`                        | Display arrays/objects as a table |
| `console.group()` / `console.groupEnd()` | Group related logs                |
| `console.time()` / `console.timeEnd()`   | Measure execution time            |
| `console.clear()`                        | Clear the console                 |

### Reading error messages

When your code breaks, the console shows the error with a clickable file and line number:

```
Uncaught TypeError: Cannot read properties of null (reading 'textContent')
    at script.js:15:23
```

This tells you:

* **What**: Tried to read `.textContent` on something that's `null`
* **Where**: `script.js`, line 15, column 23
* **Why**: Probably tried to select an element that doesn't exist (yet)

<Warning>
  If you see `null` errors when selecting elements, your JavaScript is likely running before the DOM is fully loaded. Either move your `<script>` tag to the bottom of `<body>`, or use `defer`: `<script defer src="script.js"></script>`.
</Warning>

## Network panel

The Network panel shows every HTTP request the page makes — HTML, CSS, JavaScript, images, and API calls. This is essential for debugging your FastAPI integration.

### What to look for

* **Status codes**: 200 (success), 404 (not found), 500 (server error), CORS errors
* **Request/response bodies**: Click a request to see what was sent and received
* **Timing**: How long each request takes
* **Headers**: Check Content-Type, Authorization, CORS headers

### Filtering API calls

Click the **Fetch/XHR** filter to show only API calls (hides images, CSS, etc.). This is the view you'll use most when debugging your frontend-backend communication.

```
Network panel → Fetch/XHR filter → Click a request → Preview/Response tab
```

<Tip>
  When debugging API issues, check the Network panel first. It shows exactly what your frontend sent and what the backend returned — no guessing required.
</Tip>

## Application panel

The Application panel lets you inspect browser storage:

* **localStorage**: Key-value pairs persisted between sessions
* **sessionStorage**: Key-value pairs cleared when the tab closes
* **Cookies**: Data sent with every request to the server

You'll use this when working with localStorage later in this section.

## DevTools workflow for debugging

When something isn't working, follow this order:

<Steps>
  <Step title="Check the Console">
    Look for red error messages. They usually tell you exactly what's wrong and where.
  </Step>

  <Step title="Inspect the element">
    Right-click the broken element → Inspect. Check if it exists, has the right classes, and has the expected content.
  </Step>

  <Step title="Check the Network panel">
    If data isn't showing up, check if the API request succeeded. Look at the status code and response body.
  </Step>

  <Step title="Add console.log">
    When the error isn't obvious, add `console.log()` statements to trace where values go wrong.
  </Step>
</Steps>

## What's next?

You know how to inspect the DOM. Now let's learn how to find specific elements in it with JavaScript.

<Card title="Selecting elements" icon="bullseye" href="/dom-browser/selecting-elements">
  Find and target HTML elements on the page
</Card>


# Event listeners
Source: https://js.maxbraglia.com/dom-browser/event-listeners

Respond to user interactions like clicks, keyboard input, and more

## Making pages interactive

An event is something that happens on the page — a click, a key press, a form submission, a mouse hover. Event listeners let you run code when these events occur.

```javascript theme={null}
const button = document.querySelector("#save-btn");

button.addEventListener("click", () => {
  console.log("Button clicked!");
});
```

That's the core pattern: select an element, call `addEventListener`, pass the event name and a function to run.

## addEventListener()

```javascript theme={null}
element.addEventListener(eventName, handlerFunction);
```

```javascript theme={null}
const button = document.querySelector("#delete-btn");

// Inline arrow function
button.addEventListener("click", () => {
  console.log("Deleted!");
});

// Named function (easier to remove later)
function handleDelete() {
  console.log("Deleted!");
}
button.addEventListener("click", handleDelete);
```

<Info>
  You can attach multiple listeners to the same element and event. They all fire in the order they were added.
</Info>

## Common events

| Event         | Fires when                      | Used on                             |
| ------------- | ------------------------------- | ----------------------------------- |
| `"click"`     | Element is clicked              | Buttons, links, any element         |
| `"dblclick"`  | Element is double-clicked       | Any element                         |
| `"input"`     | Input value changes (real-time) | `<input>`, `<textarea>`, `<select>` |
| `"change"`    | Input value changes (on blur)   | `<input>`, `<textarea>`, `<select>` |
| `"submit"`    | Form is submitted               | `<form>`                            |
| `"keydown"`   | Key is pressed                  | `<input>`, `document`               |
| `"keyup"`     | Key is released                 | `<input>`, `document`               |
| `"focus"`     | Element gains focus             | `<input>`, `<textarea>`             |
| `"blur"`      | Element loses focus             | `<input>`, `<textarea>`             |
| `"mouseover"` | Mouse enters element            | Any element                         |
| `"mouseout"`  | Mouse leaves element            | Any element                         |
| `"scroll"`    | Element is scrolled             | `window`, scrollable elements       |
| `"load"`      | Page/image finishes loading     | `window`, `<img>`                   |

### Practical examples

```javascript theme={null}
// Click
document.querySelector("#save-btn").addEventListener("click", () => {
  saveData();
});

// Real-time input (search-as-you-type)
document.querySelector("#search").addEventListener("input", (e) => {
  filterResults(e.target.value);
});

// Keyboard shortcut
document.addEventListener("keydown", (e) => {
  if (e.key === "Escape") {
    closeModal();
  }
});

// Form submission
document.querySelector("form").addEventListener("submit", (e) => {
  e.preventDefault(); // Don't reload the page
  handleSubmit();
});
```

## The event object

Every event handler receives an `event` object with details about what happened:

```javascript theme={null}
button.addEventListener("click", (event) => {
  console.log(event.type);    // "click"
  console.log(event.target);  // The element that was clicked
  console.log(event.clientX); // Mouse X position
  console.log(event.clientY); // Mouse Y position
});
```

### Key properties

| Property                  | Description                                 |
| ------------------------- | ------------------------------------------- |
| `event.target`            | The element that triggered the event        |
| `event.currentTarget`     | The element the listener is attached to     |
| `event.type`              | Event name ("click", "submit", etc.)        |
| `event.preventDefault()`  | Stop the default browser action             |
| `event.stopPropagation()` | Stop the event from bubbling up             |
| `event.key`               | Which key was pressed (for keyboard events) |

### event.target — the most useful property

`event.target` tells you exactly which element was interacted with:

```javascript theme={null}
document.querySelector("#user-list").addEventListener("click", (e) => {
  // Which <li> was clicked?
  if (e.target.tagName === "LI") {
    console.log("Clicked user:", e.target.textContent);
  }
});
```

### event.preventDefault() — stop default behavior

Some elements have built-in behaviors. `preventDefault()` stops them:

```javascript theme={null}
// Stop a form from reloading the page
form.addEventListener("submit", (e) => {
  e.preventDefault(); // Don't reload!
  // Handle submission with JavaScript instead
});

// Stop a link from navigating
link.addEventListener("click", (e) => {
  e.preventDefault(); // Don't navigate!
  // Do something else instead
});
```

<Warning>
  Forms reload the page on submit by default. You'll almost always want `e.preventDefault()` when handling forms with JavaScript. This is the single most common gotcha in form handling.
</Warning>

## Event delegation

Instead of adding a listener to every list item, add one listener to the parent and check `event.target`:

```javascript theme={null}
// ❌ Adding a listener to every item (slow for many items)
document.querySelectorAll(".user-card").forEach(card => {
  card.addEventListener("click", () => {
    console.log("Card clicked");
  });
});

// ✅ One listener on the parent (event delegation)
document.querySelector("#user-list").addEventListener("click", (e) => {
  const card = e.target.closest(".user-card");
  if (card) {
    console.log("Card clicked:", card.dataset.userId);
  }
});
```

Benefits of event delegation:

* Works for elements added **after** the listener is set up (dynamically created elements)
* One listener instead of hundreds — better performance
* No need to re-attach listeners when the list changes

<Tip>
  `element.closest(selector)` walks up the DOM tree from the clicked element and returns the first ancestor matching the selector. It's essential for event delegation — it finds the container you care about, even if the user clicked a child element inside it.
</Tip>

## Removing event listeners

To remove a listener, you need a reference to the same function:

```javascript theme={null}
function handleClick() {
  console.log("Clicked!");
}

// Add
button.addEventListener("click", handleClick);

// Remove
button.removeEventListener("click", handleClick);
```

```javascript theme={null}
// ❌ This doesn't work — different function references
button.addEventListener("click", () => console.log("Click!"));
button.removeEventListener("click", () => console.log("Click!")); // Not the same function

// ✅ Use a named function
function handler() { console.log("Click!"); }
button.addEventListener("click", handler);
button.removeEventListener("click", handler); // Same function reference
```

### One-time listeners

```javascript theme={null}
// Listener fires once, then removes itself
button.addEventListener("click", () => {
  console.log("This only fires once!");
}, { once: true });
```

## What's next?

You can handle clicks and keyboard events. Let's put it all together with the most common interactive element — forms.

<Card title="Form handling" icon="pen-to-square" href="/dom-browser/form-handling">
  Get form values, validate input, and handle submissions
</Card>


# Form handling
Source: https://js.maxbraglia.com/dom-browser/form-handling

Get form values, validate input, and handle form submissions

## Forms are everywhere

Every web app has forms — login, signup, search, settings, creating content. In vanilla JavaScript, you handle forms by listening for the `submit` event, reading input values, and sending data to your backend.

## Getting form values

### Individual input values

```javascript theme={null}
// HTML: <input id="username" value="sarah_chen">
const input = document.querySelector("#username");
console.log(input.value); // "sarah_chen"
```

### Different input types

```javascript theme={null}
// Text input
const name = document.querySelector("#name").value; // "Sarah Chen"

// Number input
const age = Number(document.querySelector("#age").value); // 28

// Checkbox
const agreed = document.querySelector("#terms").checked; // true or false

// Radio buttons
const selected = document.querySelector('input[name="plan"]:checked');
const plan = selected ? selected.value : null; // "pro"

// Select dropdown
const role = document.querySelector("#role").value; // "admin"

// Textarea
const bio = document.querySelector("#bio").value; // "Full-stack developer..."
```

<Info>
  Input values are always **strings**, even from `<input type="number">`. Convert them with `Number()` when you need a number. The `checked` property on checkboxes is a boolean.
</Info>

### FormData — read all values at once

`FormData` collects all named inputs in a form into a single object:

```html theme={null}
<form id="user-form">
  <input name="name" value="Sarah Chen">
  <input name="email" value="sarah@example.com">
  <select name="role">
    <option value="admin" selected>Admin</option>
  </select>
</form>
```

```javascript theme={null}
const form = document.querySelector("#user-form");
const formData = new FormData(form);

// Read individual values
console.log(formData.get("name"));  // "Sarah Chen"
console.log(formData.get("email")); // "sarah@example.com"
console.log(formData.get("role"));  // "admin"

// Convert to a plain object
const data = Object.fromEntries(formData);
console.log(data);
// { name: "Sarah Chen", email: "sarah@example.com", role: "admin" }
```

<Tip>
  `Object.fromEntries(new FormData(form))` is the cleanest way to get all form values as a plain object. It requires each input to have a `name` attribute.
</Tip>

## Handling form submission

The standard pattern: listen for `submit`, prevent the default page reload, read values, and send to your API.

```javascript theme={null}
const form = document.querySelector("#create-user-form");

form.addEventListener("submit", async (e) => {
  e.preventDefault(); // Don't reload the page!

  const formData = new FormData(form);
  const userData = Object.fromEntries(formData);

  try {
    const response = await fetch("/api/users", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(userData),
    });

    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const newUser = await response.json();
    console.log("Created:", newUser);
    form.reset(); // Clear the form
  } catch (error) {
    console.error("Failed to create user:", error);
  }
});
```

<Warning>
  `e.preventDefault()` is required. Without it, the browser submits the form the old-fashioned way — a full page reload with form data in the URL. You'll lose your application state. This is the most common form handling mistake.
</Warning>

## Real-time input handling

### The `input` event — fires on every keystroke

```javascript theme={null}
const searchInput = document.querySelector("#search");
const resultsList = document.querySelector("#results");

searchInput.addEventListener("input", (e) => {
  const query = e.target.value.toLowerCase();

  // Filter and display results as the user types
  const filtered = users.filter(u =>
    u.name.toLowerCase().includes(query)
  );

  resultsList.innerHTML = filtered
    .map(u => `<li>${u.name}</li>`)
    .join("");
});
```

### The `change` event — fires when input loses focus

```javascript theme={null}
const select = document.querySelector("#theme-select");

select.addEventListener("change", (e) => {
  document.body.className = e.target.value; // "light" or "dark"
});
```

| Event    | Fires when                            | Best for                               |
| -------- | ------------------------------------- | -------------------------------------- |
| `input`  | Every keystroke / change              | Search, live preview, character counts |
| `change` | Input loses focus (or select changes) | Dropdowns, radio buttons, checkboxes   |

## Basic validation

### HTML validation attributes

The browser has built-in validation. Use HTML attributes first:

```html theme={null}
<form id="signup-form">
  <input name="name" required minlength="2" maxlength="50">
  <input name="email" type="email" required>
  <input name="age" type="number" min="13" max="120">
  <input name="website" type="url">
  <button type="submit">Sign Up</button>
</form>
```

The browser shows error messages automatically. The form won't submit until all validations pass.

### JavaScript validation

For more complex rules, validate in your submit handler:

```javascript theme={null}
form.addEventListener("submit", async (e) => {
  e.preventDefault();

  const data = Object.fromEntries(new FormData(form));
  const errors = [];

  // Custom validation
  if (data.name.trim().length < 2) {
    errors.push("Name must be at least 2 characters");
  }
  if (!data.email.includes("@")) {
    errors.push("Please enter a valid email");
  }
  if (data.password.length < 8) {
    errors.push("Password must be at least 8 characters");
  }
  if (data.password !== data.confirmPassword) {
    errors.push("Passwords don't match");
  }

  if (errors.length > 0) {
    showErrors(errors);
    return; // Don't submit
  }

  // Validation passed — submit to API
  await submitForm(data);
});

function showErrors(errors) {
  const errorContainer = document.querySelector("#form-errors");
  errorContainer.innerHTML = errors
    .map(err => `<p class="error">${err}</p>`)
    .join("");
}
```

### Disabling the submit button

```javascript theme={null}
const submitBtn = form.querySelector('button[type="submit"]');

form.addEventListener("submit", async (e) => {
  e.preventDefault();
  submitBtn.disabled = true;
  submitBtn.textContent = "Saving...";

  try {
    await submitToAPI();
    form.reset();
  } catch (error) {
    showError(error.message);
  } finally {
    submitBtn.disabled = false;
    submitBtn.textContent = "Save";
  }
});
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting preventDefault on form submit">
    ```javascript theme={null}
    // ❌ Page reloads — data is lost
    form.addEventListener("submit", (e) => {
      const data = Object.fromEntries(new FormData(form));
      fetch("/api/users", { method: "POST", body: JSON.stringify(data) });
      // Page reloads before fetch completes!
    });

    // ✅ Prevent default first
    form.addEventListener("submit", async (e) => {
      e.preventDefault();
      const data = Object.fromEntries(new FormData(form));
      await fetch("/api/users", { method: "POST", body: JSON.stringify(data) });
    });
    ```

    <Warning>
      Without `e.preventDefault()`, the browser handles the form submission itself — reloading the page and appending form data to the URL. Your JavaScript fetch never completes.
    </Warning>
  </Accordion>

  <Accordion title="Reading values at load time instead of submit time">
    ```javascript theme={null}
    // ❌ Wrong: reads value when page loads (empty)
    const nameInput = document.querySelector("#name");
    const name = nameInput.value; // "" — user hasn't typed yet

    form.addEventListener("submit", (e) => {
      e.preventDefault();
      console.log(name); // Always "" — captured the initial empty value
    });

    // ✅ Correct: read value when form is submitted
    form.addEventListener("submit", (e) => {
      e.preventDefault();
      const name = document.querySelector("#name").value; // Current value
      console.log(name); // "Sarah Chen" — whatever the user typed
    });
    ```
  </Accordion>

  <Accordion title="Missing name attributes on inputs">
    ```html theme={null}
    <!-- ❌ FormData can't read inputs without name attributes -->
    <input id="username" type="text">

    <!-- ✅ Add name attribute -->
    <input id="username" name="username" type="text">
    ```

    <Warning>
      `FormData` uses the `name` attribute, not `id`. If your inputs don't have `name`, `Object.fromEntries(new FormData(form))` will return an empty object.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can handle forms and user input. Let's wrap up the DOM & Browser section with localStorage — persisting data between page loads.

<Card title="Local storage" icon="floppy-disk" href="/dom-browser/local-storage">
  Persist data in the browser between page loads
</Card>


# Local storage
Source: https://js.maxbraglia.com/dom-browser/local-storage

Persist data in the browser between page loads using localStorage

## Data that survives a page reload

By default, JavaScript data disappears when you close or refresh the page. `localStorage` lets you store data in the browser that persists across page loads, tab closes, and even browser restarts.

```javascript theme={null}
// Save
localStorage.setItem("username", "sarah_chen");

// Retrieve (even after closing and reopening the browser)
const username = localStorage.getItem("username");
console.log(username); // "sarah_chen"
```

## The four methods

```javascript theme={null}
// Store a value
localStorage.setItem("theme", "dark");

// Get a value
const theme = localStorage.getItem("theme"); // "dark"

// Remove a specific value
localStorage.removeItem("theme");

// Clear everything
localStorage.clear();
```

That's the entire API. Four methods, all synchronous, all straightforward.

## localStorage only stores strings

This is the most important thing to know. `localStorage` values are always strings.

```javascript theme={null}
// ❌ Storing a number — gets converted to string
localStorage.setItem("count", 42);
const count = localStorage.getItem("count");
console.log(count);        // "42" (string!)
console.log(typeof count); // "string"
console.log(count + 1);    // "421" (string concatenation, not addition)

// ✅ Convert back to number
const count = Number(localStorage.getItem("count"));
console.log(count + 1); // 43
```

## Storing objects and arrays

Since localStorage only stores strings, you need `JSON.stringify()` and `JSON.parse()`:

```javascript theme={null}
// Save an object
const user = { name: "Sarah Chen", role: "admin", theme: "dark" };
localStorage.setItem("user", JSON.stringify(user));

// Load it back
const saved = localStorage.getItem("user");
const loadedUser = JSON.parse(saved);
console.log(loadedUser.name); // "Sarah Chen"
```

```javascript theme={null}
// Save an array
const favorites = ["React", "FastAPI", "TypeScript"];
localStorage.setItem("favorites", JSON.stringify(favorites));

// Load it back
const loadedFavorites = JSON.parse(localStorage.getItem("favorites"));
console.log(loadedFavorites); // ["React", "FastAPI", "TypeScript"]
```

<Warning>
  If you forget `JSON.stringify()` when saving an object, you'll store the useless string `"[object Object]"`. Always stringify objects before saving and parse after loading.
</Warning>

### Safe loading with a fallback

`localStorage.getItem()` returns `null` if the key doesn't exist. Handle this:

```javascript theme={null}
// This returns null if "settings" doesn't exist (it does NOT crash)
const settings = JSON.parse(localStorage.getItem("settings"));
console.log(settings); // null

// ✅ Safe with fallback
const settings = JSON.parse(localStorage.getItem("settings")) || {
  theme: "light",
  fontSize: 14,
};
```

If the stored value is invalid JSON (for example, someone manually edited it in DevTools), `JSON.parse()` *will* throw. Use `try/catch` if the data might be corrupted.

<Tip>
  Always provide a fallback when loading from localStorage. The data might not exist yet (first visit), or the user might have cleared their browser data.
</Tip>

## Practical use cases

### Saving user preferences

```javascript theme={null}
// Theme toggle that remembers the choice
const themeToggle = document.querySelector("#theme-toggle");

// Load saved preference on page load
const savedTheme = localStorage.getItem("theme") || "light";
document.body.className = savedTheme;

// Save when user changes theme
themeToggle.addEventListener("click", () => {
  const newTheme = document.body.classList.contains("dark") ? "light" : "dark";
  document.body.className = newTheme;
  localStorage.setItem("theme", newTheme);
});
```

### Saving form drafts

```javascript theme={null}
const form = document.querySelector("#post-form");
const textarea = document.querySelector("#post-content");

// Load saved draft on page load
const savedDraft = localStorage.getItem("post-draft");
if (savedDraft) {
  textarea.value = savedDraft;
}

// Auto-save as user types
textarea.addEventListener("input", () => {
  localStorage.setItem("post-draft", textarea.value);
});

// Clear draft when form is submitted
form.addEventListener("submit", (e) => {
  e.preventDefault();
  localStorage.removeItem("post-draft");
  // ... submit to API
});
```

### Simple shopping cart

```javascript theme={null}
function getCart() {
  return JSON.parse(localStorage.getItem("cart")) || [];
}

function saveCart(cart) {
  localStorage.setItem("cart", JSON.stringify(cart));
}

function addToCart(product) {
  const cart = getCart();
  cart.push(product);
  saveCart(cart);
}

function removeFromCart(productId) {
  const cart = getCart().filter(item => item.id !== productId);
  saveCart(cart);
}

// Usage
addToCart({ id: 1, name: "Wireless Headphones", price: 79.99 });
addToCart({ id: 2, name: "USB-C Cable", price: 12.99 });
console.log(getCart()); // Both items, even after page refresh
```

## localStorage vs other storage

| Storage          | Capacity  | Persists         | Shared with server            | Best for                   |
| ---------------- | --------- | ---------------- | ----------------------------- | -------------------------- |
| `localStorage`   | \~5–10 MB | Until cleared    | No                            | Preferences, drafts, cache |
| `sessionStorage` | \~5–10 MB | Until tab closes | No                            | Temporary state            |
| Cookies          | \~4 KB    | Configurable     | Yes (sent with every request) | Auth tokens                |
| Backend database | Unlimited | Until deleted    | N/A                           | User data, content         |

<Info>
  `sessionStorage` works exactly like `localStorage` but data is cleared when the browser tab closes. Use it for truly temporary data like "which tab is selected" or "scroll position."
</Info>

## When NOT to use localStorage

* **Sensitive data** — never store passwords, tokens, or personal data. localStorage is readable by any JavaScript on the page (including malicious scripts).
* **Large data** — the \~5-10 MB limit makes it unsuitable for images, videos, or large datasets.
* **Data that must sync across devices** — localStorage is per-browser, per-device. Use your backend database for data that should follow the user.
* **Critical application data** — users can clear localStorage at any time. Don't store anything your app can't recreate from the backend.

<Warning>
  Never store authentication tokens in localStorage. It's vulnerable to XSS attacks — any JavaScript on the page can read it. Use HTTP-only cookies for auth tokens instead.
</Warning>

## Inspecting localStorage in DevTools

Open DevTools → Application tab → Local Storage (in the sidebar). You can:

* View all stored key-value pairs
* Edit values directly
* Delete individual keys or clear everything
* Watch values change in real time

## What's next?

You've covered the DOM and browser APIs — selecting elements, modifying the page, handling events, working with forms, and persisting data. These are the building blocks that every framework builds on.

Next up: React. You'll see how React takes everything you've learned — DOM manipulation, event handling, state management — and wraps it in a component-based architecture that scales to real applications.

<Card title="What is React?" icon="atom" href="/react-essentials/what-is-react">
  Understand why React exists and what problems it solves
</Card>


# Modifying elements
Source: https://js.maxbraglia.com/dom-browser/modifying-elements

Change text, styles, attributes, and classes of HTML elements

## Changing what's on the page

Once you've selected an element, you can change anything about it — its text, HTML, styles, classes, and attributes. This is how vanilla JavaScript makes pages dynamic.

## Changing text content

### textContent — plain text

```javascript theme={null}
const heading = document.querySelector("h1");

// Read
console.log(heading.textContent); // "Welcome"

// Write
heading.textContent = "Hello, Sarah!";
```

`textContent` sets or gets the plain text of an element. It's safe — any HTML in the string is displayed as text, not rendered.

```javascript theme={null}
// HTML is escaped — shows the literal tags
heading.textContent = "<em>Hello</em>"; // Displays: <em>Hello</em>
```

### innerHTML — HTML content

```javascript theme={null}
const container = document.querySelector(".user-info");

// Read — includes HTML tags
console.log(container.innerHTML); // "<strong>Sarah</strong> — Admin"

// Write — HTML is parsed and rendered
container.innerHTML = "<strong>Sarah Chen</strong> — <em>Editor</em>";
```

`innerHTML` parses and renders HTML. Use it when you need to insert structured content.

<Warning>
  Never set `innerHTML` with user input. It creates a cross-site scripting (XSS) vulnerability. If a user types `<script>alert('hacked')</script>`, it will execute. Use `textContent` for user-provided data.
</Warning>

### When to use each

| Method        | Use case                                     | Safe from XSS?      |
| ------------- | -------------------------------------------- | ------------------- |
| `textContent` | Setting plain text                           | Yes                 |
| `innerHTML`   | Setting HTML structure                       | No — sanitize first |
| `innerText`   | Like `textContent` but respects CSS (slower) | Yes                 |

<Tip>
  Default to `textContent`. Only use `innerHTML` when you specifically need to set HTML, and never with user input.
</Tip>

## Changing styles

### Inline styles

```javascript theme={null}
const card = document.querySelector(".card");

// Set individual properties (camelCase, not kebab-case)
card.style.backgroundColor = "#f0f9ff";
card.style.padding = "16px";
card.style.borderRadius = "8px";
card.style.display = "none"; // Hide the element

// Read a style
console.log(card.style.backgroundColor); // "rgb(240, 249, 255)"
```

CSS property names use **camelCase** in JavaScript:

| CSS                | JavaScript        |
| ------------------ | ----------------- |
| `background-color` | `backgroundColor` |
| `font-size`        | `fontSize`        |
| `border-radius`    | `borderRadius`    |
| `z-index`          | `zIndex`          |
| `margin-top`       | `marginTop`       |

### Removing an inline style

```javascript theme={null}
// Set to empty string to remove
card.style.backgroundColor = "";

// Or remove all inline styles
card.removeAttribute("style");
```

<Info>
  `element.style` only reads and sets **inline** styles. It won't show styles from your CSS files. To read the computed (final) style, use `getComputedStyle(element)`.
</Info>

## Adding and removing classes

This is the preferred way to change styles. Instead of setting individual CSS properties, toggle classes that are defined in your stylesheet.

### classList API

```javascript theme={null}
const button = document.querySelector(".btn");

// Add a class
button.classList.add("active");
// <button class="btn active">

// Remove a class
button.classList.remove("active");
// <button class="btn">

// Toggle — add if missing, remove if present
button.classList.toggle("active");

// Check if a class exists
if (button.classList.contains("active")) {
  console.log("Button is active");
}

// Add multiple classes
button.classList.add("primary", "large");

// Remove multiple classes
button.classList.remove("primary", "large");
```

### Practical examples

```javascript theme={null}
// Show/hide an element
const modal = document.querySelector(".modal");
modal.classList.toggle("hidden");

// Highlight the active navigation link
const navLinks = document.querySelectorAll(".nav-link");
navLinks.forEach(link => link.classList.remove("active"));
clickedLink.classList.add("active");

// Dark mode toggle
document.body.classList.toggle("dark-mode");
```

```css theme={null}
/* Your CSS file */
.hidden { display: none; }
.active { color: #3b82f6; font-weight: bold; }
.dark-mode { background: #1a1a2e; color: #eee; }
```

<Tip>
  Prefer `classList` over `element.style` for most visual changes. CSS classes are reusable, easier to maintain, and keep your JavaScript focused on logic rather than styling.
</Tip>

## Changing attributes

### setAttribute / getAttribute

```javascript theme={null}
const link = document.querySelector("a.docs-link");

// Read an attribute
console.log(link.getAttribute("href")); // "/docs"

// Set an attribute
link.setAttribute("href", "/new-docs");
link.setAttribute("target", "_blank");

// Remove an attribute
link.removeAttribute("target");

// Check if an attribute exists
link.hasAttribute("target"); // false
```

### Direct property access

Most common attributes have matching properties:

```javascript theme={null}
const img = document.querySelector("img.avatar");

// These work the same as setAttribute/getAttribute
img.src = "/images/sarah.jpg";
img.alt = "Sarah Chen's avatar";
img.width = 64;

const input = document.querySelector("input.email");
input.value = "sarah@example.com";
input.placeholder = "Enter your email";
input.disabled = true;
input.required = true;
```

### data attributes

Custom `data-*` attributes are accessed through the `dataset` property:

```javascript theme={null}
// HTML: <div data-user-id="42" data-role="admin">
const card = document.querySelector(".user-card");

// Read — kebab-case becomes camelCase
console.log(card.dataset.userId); // "42"
console.log(card.dataset.role);   // "admin"

// Write
card.dataset.status = "active";
// HTML becomes: <div data-user-id="42" data-role="admin" data-status="active">
```

<Info>
  `data-*` attributes are always strings. If you store a number, you'll need to convert it: `Number(card.dataset.userId)`.
</Info>

## Showing and hiding elements

Three common patterns:

```javascript theme={null}
const element = document.querySelector(".notification");

// 1. CSS class (preferred)
element.classList.toggle("hidden"); // Uses .hidden { display: none }

// 2. Style property
element.style.display = "none";  // Hide
element.style.display = "";      // Show (revert to CSS default)

// 3. Hidden attribute
element.hidden = true;  // Hide
element.hidden = false; // Show
```

<Tip>
  The CSS class approach is cleanest. Define a `.hidden` class in CSS and toggle it with `classList.toggle("hidden")`. This keeps your styling in CSS and your logic in JavaScript.
</Tip>

## What's next?

You can modify existing elements. Now let's learn how to create new elements from scratch and add them to the page.

<Card title="Creating elements" icon="plus" href="/dom-browser/creating-elements">
  Dynamically add new HTML elements to the page
</Card>


# Selecting elements
Source: https://js.maxbraglia.com/dom-browser/selecting-elements

Find and target HTML elements on the page using JavaScript

## Finding elements on the page

Before you can change anything on a page, you need to find it. JavaScript gives you two main methods — both use CSS selectors, so if you know CSS, you already know how to use them.

## document.querySelector()

Returns the **first** element that matches a CSS selector:

```javascript theme={null}
// Select by tag
const heading = document.querySelector("h1");

// Select by class
const card = document.querySelector(".user-card");

// Select by ID
const sidebar = document.querySelector("#sidebar");

// Select by attribute
const emailInput = document.querySelector('input[type="email"]');

// Select nested elements
const firstItem = document.querySelector("ul.nav > li");
```

If no element matches, `querySelector` returns `null` — not an error.

```javascript theme={null}
const missing = document.querySelector(".does-not-exist");
console.log(missing); // null

// ❌ This will crash
missing.textContent = "Hello"; // TypeError: Cannot read properties of null

// ✅ Check first
if (missing) {
  missing.textContent = "Hello";
}
```

<Warning>
  `querySelector` returns `null` when it can't find a match. Always check for `null` if you're not 100% sure the element exists, or you'll get `TypeError: Cannot read properties of null`.
</Warning>

## document.querySelectorAll()

Returns **all** matching elements as a `NodeList`:

```javascript theme={null}
// Get all paragraphs
const paragraphs = document.querySelectorAll("p");
console.log(paragraphs.length); // 5

// Get all elements with the class "card"
const cards = document.querySelectorAll(".card");

// Get all checked checkboxes
const checked = document.querySelectorAll('input[type="checkbox"]:checked');
```

### Iterating over results

```javascript theme={null}
const cards = document.querySelectorAll(".card");

// for...of works
for (const card of cards) {
  console.log(card.textContent);
}

// .forEach() works
cards.forEach(card => {
  card.classList.add("visible");
});

// Array methods need conversion
const cardTexts = [...cards].map(card => card.textContent);
// or: Array.from(cards).map(card => card.textContent)
```

<Info>
  `querySelectorAll` returns a `NodeList`, not an array. It has `.forEach()` but not `.map()`, `.filter()`, etc. Spread it into an array with `[...nodeList]` when you need array methods.
</Info>

## Common CSS selectors

You use the same selectors as CSS. Here's a quick reference:

| Selector   | Example            | Matches                                 |
| ---------- | ------------------ | --------------------------------------- |
| Tag        | `"p"`              | All `<p>` elements                      |
| Class      | `".card"`          | Elements with `class="card"`            |
| ID         | `"#sidebar"`       | Element with `id="sidebar"`             |
| Attribute  | `'[data-id="5"]'`  | Elements with `data-id="5"`             |
| Child      | `"ul > li"`        | Direct `<li>` children of `<ul>`        |
| Descendant | `"form input"`     | Any `<input>` inside a `<form>`         |
| Multiple   | `"h1, h2, h3"`     | All `<h1>`, `<h2>`, and `<h3>` elements |
| Pseudo     | `"li:first-child"` | First `<li>` in its parent              |

### Practical examples

```javascript theme={null}
// Form inputs
const nameInput = document.querySelector("#user-form input[name='username']");

// Navigation links
const navLinks = document.querySelectorAll("nav a");

// Active tab
const activeTab = document.querySelector(".tab.active");

// Data attributes (great for JS hooks)
const modal = document.querySelector('[data-modal="settings"]');
```

<Tip>
  Use `data-*` attributes to select elements meant for JavaScript interaction. This keeps your JS selectors separate from your CSS classes: `<button data-action="delete">` instead of `<button class="delete-btn">`.
</Tip>

## Older methods (still common)

You'll see these in older code and tutorials:

```javascript theme={null}
// By ID — no # prefix needed
const sidebar = document.getElementById("sidebar");

// By class name — returns a live HTMLCollection
const cards = document.getElementsByClassName("card");

// By tag name — returns a live HTMLCollection
const paragraphs = document.getElementsByTagName("p");
```

<Tabs>
  <Tab title="Modern (use this)">
    ```javascript theme={null}
    const sidebar = document.querySelector("#sidebar");
    const cards = document.querySelectorAll(".card");
    ```
  </Tab>

  <Tab title="Older (you'll still see)">
    ```javascript theme={null}
    const sidebar = document.getElementById("sidebar");
    const cards = document.getElementsByClassName("card");
    ```
  </Tab>
</Tabs>

`querySelector` / `querySelectorAll` are the modern standard. They're more flexible (any CSS selector) and more consistent (`querySelectorAll` always returns a static `NodeList`).

## Scope your selectors

You can call `querySelector` on any element, not just `document`:

```javascript theme={null}
const form = document.querySelector("#user-form");

// Search only inside the form
const nameInput = form.querySelector('input[name="username"]');
const submitBtn = form.querySelector('button[type="submit"]');
```

This is useful when you have multiple similar structures on the page and need to target elements within a specific container.

## Common mistakes

<AccordionGroup>
  <Accordion title="Selecting elements before they exist">
    ```html theme={null}
    <!-- ❌ Script runs before the body is parsed -->
    <head>
      <script src="app.js"></script>
    </head>
    <body>
      <h1>Hello</h1>
    </body>
    ```

    ```javascript theme={null}
    // app.js — h1 doesn't exist yet when this runs!
    const heading = document.querySelector("h1"); // null
    ```

    ```html theme={null}
    <!-- ✅ Use defer — script runs after DOM is ready -->
    <head>
      <script defer src="app.js"></script>
    </head>
    <body>
      <h1>Hello</h1>
    </body>
    ```

    <Warning>
      Scripts in `<head>` run before `<body>` is parsed. Use `defer` on your script tag, or place the `<script>` at the bottom of `<body>`. The `defer` approach is modern and preferred.
    </Warning>
  </Accordion>

  <Accordion title="Forgetting the dot or hash in selectors">
    ```javascript theme={null}
    // ❌ Wrong — missing . for class
    const card = document.querySelector("card");      // Looks for <card> element

    // ✅ Correct
    const card = document.querySelector(".card");      // Looks for class="card"

    // ❌ Wrong — missing # for ID
    const sidebar = document.querySelector("sidebar"); // Looks for <sidebar> element

    // ✅ Correct
    const sidebar = document.querySelector("#sidebar"); // Looks for id="sidebar"
    ```
  </Accordion>

  <Accordion title="Treating querySelectorAll like an array">
    ```javascript theme={null}
    const items = document.querySelectorAll(".item");

    // ❌ Won't work — NodeList doesn't have .map()
    const names = items.map(item => item.textContent);

    // ✅ Spread into an array first
    const names = [...items].map(item => item.textContent);
    ```
  </Accordion>
</AccordionGroup>

## What's next?

You can find elements. Now let's change them — text, styles, classes, and attributes.

<Card title="Modifying elements" icon="pen" href="/dom-browser/modifying-elements">
  Change text, styles, attributes, and classes
</Card>


# What is the DOM
Source: https://js.maxbraglia.com/dom-browser/what-is-dom

Understand how browsers represent web pages as a tree of objects you can manipulate

## The page is a tree of objects

When a browser loads an HTML file, it doesn't just display text. It parses the HTML and builds an in-memory tree of objects called the **Document Object Model** (DOM). Every HTML element becomes a JavaScript object you can read, modify, and delete.

```html theme={null}
<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <h1>Hello</h1>
    <p>Welcome to my app</p>
  </body>
</html>
```

The browser turns this into a tree:

```
document
└── html
    ├── head
    │   └── title
    │       └── "My App"
    └── body
        ├── h1
        │   └── "Hello"
        └── p
            └── "Welcome to my app"
```

Every box in this tree is a **node**. Elements, text, and even comments are nodes. JavaScript can access and change any of them.

## The `document` object

`document` is your entry point to the DOM. It's a global object available in any browser JavaScript — you don't need to import anything.

```javascript theme={null}
// The whole page
console.log(document);

// The <html> element
console.log(document.documentElement);

// The <head> element
console.log(document.head);

// The <body> element
console.log(document.body);

// The page title
console.log(document.title); // "My App"
document.title = "New Title"; // Changes the browser tab title
```

<Info>
  `document` is only available in the browser. If you try to use it in Node.js, you'll get `ReferenceError: document is not defined`. This is a browser-only API.
</Info>

## What can you do with the DOM?

The DOM lets JavaScript interact with the page:

| Action                | Example                                     |
| --------------------- | ------------------------------------------- |
| **Find** elements     | `document.querySelector(".user-card")`      |
| **Read** content      | `element.textContent`                       |
| **Change** content    | `element.textContent = "New text"`          |
| **Change** styles     | `element.style.color = "red"`               |
| **Add** elements      | `parent.appendChild(newElement)`            |
| **Remove** elements   | `element.remove()`                          |
| **Listen** for events | `button.addEventListener("click", handler)` |

This is how JavaScript makes web pages interactive. Without the DOM, a page would be static HTML — no clicking, no updating, no fetching data and displaying it.

## How this connects to React

Here's the key insight: **React is a DOM manipulation library**. Everything React does — rendering components, updating the UI, handling events — ultimately translates to DOM operations.

```javascript theme={null}
// Vanilla JavaScript (what we'll learn in this section)
const heading = document.querySelector("h1");
heading.textContent = "Hello, Sarah!";

// React (what you'll learn later) — does the same thing under the hood
function Greeting() {
  return <h1>Hello, Sarah!</h1>;
}
```

React abstracts away manual DOM manipulation so you don't have to do it yourself. But understanding the DOM helps you:

* Debug React applications (the Elements panel shows the real DOM)
* Understand why React re-renders
* Work with libraries that touch the DOM directly
* Handle edge cases React can't cover

<Tip>
  You don't need to master manual DOM manipulation to use React. But understanding what's happening underneath makes you a better React developer. Think of this section as learning what your car engine does — you don't need to rebuild it, but knowing how it works helps when something goes wrong.
</Tip>

## DOM vs HTML

The DOM is not your HTML file. The browser builds the DOM *from* your HTML, but they can differ:

```html theme={null}
<!-- Your HTML file -->
<div id="app"></div>
```

```javascript theme={null}
// JavaScript adds content that wasn't in the original HTML
const app = document.querySelector("#app");
app.innerHTML = "<h1>Hello!</h1><p>This wasn't in the HTML file</p>";
```

After this JavaScript runs, the DOM has an `h1` and `p` inside `#app`, but the HTML file still just says `<div id="app"></div>`. The DOM is the **live, current state** of the page.

<Info>
  When you "View Source" in the browser, you see the original HTML. When you inspect with DevTools, you see the current DOM. They're often different because JavaScript modifies the DOM after the page loads.
</Info>

## What's next?

Now that you know what the DOM is, let's learn the tool you'll use every day to inspect and debug it — browser DevTools.

<Card title="Browser DevTools" icon="wrench" href="/dom-browser/dev-tools">
  Inspect, debug, and test your JavaScript in the browser
</Card>


# API client layer
Source: https://js.maxbraglia.com/full-stack/api-client-layer

Separate API calls from components for cleaner, more maintainable code

## Stop putting fetch in components

Here's what most beginners do — scatter `fetch()` calls throughout their components:

```jsx theme={null}
// ❌ API logic mixed into the component
function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch(`${import.meta.env.VITE_API_BASE_URL}/api/users`)
      .then(r => {
        if (!r.ok) throw new Error(`HTTP ${r.status}`);
        return r.json();
      })
      .then(data => setUsers(data))
      .catch(err => console.error(err));
  }, []);

  // ... render
}
```

This works, but it creates problems: the same URL and error-handling logic gets duplicated in every component that needs users. If the API changes, you fix it in 10 places instead of 1.

<Info>
  The companion repo already uses an API client file (`frontend/src/api/users.ts`) with this pattern. In this lesson, we stay in JavaScript and then add an optional shared `client.js` helper as a teaching step to reduce repetition further.
</Info>

## The API client pattern

Create a dedicated file for each resource's API calls:

```jsx theme={null}
// frontend/src/api/users.js
const API_URL = import.meta.env.VITE_API_BASE_URL;

export async function getUsers() {
  const response = await fetch(`${API_URL}/api/users`);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

export async function getUser(id) {
  const response = await fetch(`${API_URL}/api/users/${id}`);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

export async function createUser(userData) {
  const response = await fetch(`${API_URL}/api/users`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(userData),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

export async function updateUser(id, userData) {
  const response = await fetch(`${API_URL}/api/users/${id}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(userData),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

export async function deleteUser(id) {
  const response = await fetch(`${API_URL}/api/users/${id}`, {
    method: "DELETE",
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
}
```

Now your components are clean:

```jsx theme={null}
// frontend/src/pages/UserList.jsx
import { useState, useEffect } from 'react';
import { getUsers } from '../api/users';

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    getUsers()
      .then(data => setUsers(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  // ... render
}
```

The component doesn't know about URLs, headers, or HTTP methods. It just calls `getUsers()` and gets data back.

## File structure

```
frontend/src/
├── api/
│   ├── users.js        # User CRUD operations
│   ├── products.js     # Product CRUD operations
│   └── auth.js         # Login, logout, register
├── components/
│   ├── UserCard.jsx
│   └── UserForm.jsx
├── pages/
│   └── Dashboard.jsx
└── App.jsx
```

One API file per resource. Each file exports functions that match the backend endpoints.

<Tip>
  This mirrors how your FastAPI backend is organized. You have a `users` router in Python and a `users.js` API client in JavaScript. When you add a new endpoint to FastAPI, you add a matching function to the API client.
</Tip>

## Reducing duplication with a helper

Notice how every function repeats the same pattern: fetch, check response, parse JSON. Extract a helper:

```jsx theme={null}
// frontend/src/api/client.js
const API_URL = import.meta.env.VITE_API_BASE_URL;

export async function apiClient(endpoint, options = {}) {
  const response = await fetch(`${API_URL}${endpoint}`, {
    headers: {
      "Content-Type": "application/json",
      ...options.headers,
    },
    ...options,
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail || `HTTP ${response.status}`);
  }

  // DELETE often returns no body
  if (response.status === 204) return null;
  return response.json();
}
```

Now your API functions are one-liners:

```jsx theme={null}
// frontend/src/api/users.js
import { apiClient } from './client';

export const getUsers = () =>
  apiClient("/api/users");

export const getUser = (id) =>
  apiClient(`/api/users/${id}`);

export const createUser = (data) =>
  apiClient("/api/users", { method: "POST", body: JSON.stringify(data) });

export const updateUser = (id, data) =>
  apiClient(`/api/users/${id}`, { method: "PUT", body: JSON.stringify(data) });

export const deleteUser = (id) =>
  apiClient(`/api/users/${id}`, { method: "DELETE" });
```

<Info>
  The `apiClient` helper reads the FastAPI error message (`error.detail`) when available. This means your backend's validation errors ("Email is required") show up directly in the frontend — no extra work needed.
</Info>

## Why this pattern matters

| Benefit                    | Explanation                                                |
| -------------------------- | ---------------------------------------------------------- |
| **Single source of truth** | API URL defined once in `client.js`                        |
| **DRY**                    | Error handling written once, not in every component        |
| **Easy to change**         | API changes? Update one file, not every component          |
| **Testable**               | You can mock `getUsers()` in tests without mocking `fetch` |
| **Readable components**    | Components focus on UI, not HTTP details                   |

This isn't over-engineering — it's the minimum level of organization you need once your app has more than 2-3 API calls.

## Using the API client in components

```jsx theme={null}
import { useState, useEffect } from 'react';
import { getUsers, createUser, deleteUser } from '../api/users';

function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    loadUsers();
  }, []);

  async function loadUsers() {
    try {
      setLoading(true);
      const data = await getUsers();
      setUsers(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  async function handleCreate(userData) {
    const newUser = await createUser(userData);
    setUsers(prev => [...prev, newUser]);
  }

  async function handleDelete(userId) {
    await deleteUser(userId);
    setUsers(prev => prev.filter(u => u.id !== userId));
  }

  // ... render with loading/error/data pattern
}
```

Clean, readable, and every API call is one function call.

## What's next?

Your API calls are organized. But how do you make sure the data your frontend sends matches what your backend expects? Let's talk about type safety.

<Card title="Type safety" icon="shield-check" href="/full-stack/type-safety">
  Ensure your frontend and backend agree on data shapes
</Card>


# Create operation
Source: https://js.maxbraglia.com/full-stack/create-operation

Build a form that sends data to your FastAPI backend and creates a new record

## The full picture

Creating a record involves three parts working together: a FastAPI endpoint, an API client function, and a React form component.

<Tabs>
  <Tab title="Backend (Python)">
    ```python theme={null}
    # backend/main.py
    class UserCreate(BaseModel):
        name: str
        email: str

    @app.post("/api/users", status_code=201)
    def create_user(user: UserCreate):
        new_user = {"id": next_id, "name": user.name, "email": user.email}
        users.append(new_user)
        return new_user
    ```
  </Tab>

  <Tab title="API Client (JS)">
    ```jsx theme={null}
    // frontend/src/api/users.js
    export async function createUser(data) {
      const response = await fetch(`${API_URL}/api/users`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return response.json();
    }
    ```
  </Tab>

  <Tab title="Component (React)">
    ```jsx theme={null}
    // frontend/src/components/CreateUserForm.jsx
    function CreateUserForm({ onUserCreated }) {
      // ... form state and submission logic
    }
    ```
  </Tab>
</Tabs>

## The form component

```jsx theme={null}
import { useState } from 'react';
import { createUser } from '../api/users';

function CreateUserForm({ onUserCreated }) {
  const [formData, setFormData] = useState({ name: "", email: "" });
  const [error, setError] = useState(null);
  const [submitting, setSubmitting] = useState(false);

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
  }

  async function handleSubmit(e) {
    e.preventDefault();
    setError(null);
    setSubmitting(true);

    try {
      const newUser = await createUser(formData);
      onUserCreated(newUser);    // Tell parent about the new user
      setFormData({ name: "", email: "" }); // Reset form
    } catch (err) {
      setError(err.message);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="name"
        value={formData.name}
        onChange={handleChange}
        placeholder="Name"
        required
      />
      <input
        name="email"
        type="email"
        value={formData.email}
        onChange={handleChange}
        placeholder="Email"
        required
      />

      {error && <p className="error">{error}</p>}

      <button type="submit" disabled={submitting}>
        {submitting ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}
```

Key details:

* **`onUserCreated` callback** — the form doesn't manage the user list, it just notifies the parent
* **`submitting` state** — disables the button to prevent double submissions
* **Form reset** — clears inputs after successful creation
* **Error display** — shows the error message from the API

## The parent component

The parent owns the user list and passes the callback:

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);

  function handleUserCreated(newUser) {
    setUsers(prev => [...prev, newUser]);
  }

  return (
    <div>
      <h1>Users</h1>
      <CreateUserForm onUserCreated={handleUserCreated} />
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name} — {user.email}</li>
        ))}
      </ul>
    </div>
  );
}
```

When the form creates a user, the API returns the full user object (with its new `id`). The parent adds it to the list. The UI updates instantly — no need to refetch.

## Adding validation

Combine frontend validation with backend error handling:

```jsx theme={null}
function CreateUserForm({ onUserCreated }) {
  const [formData, setFormData] = useState({ name: "", email: "" });
  const [errors, setErrors] = useState({});
  const [submitting, setSubmitting] = useState(false);

  function validate() {
    const newErrors = {};
    if (!formData.name.trim()) newErrors.name = "Name is required";
    if (!formData.email.trim()) newErrors.email = "Email is required";
    else if (!formData.email.includes("@")) newErrors.email = "Invalid email";
    return newErrors;
  }

  async function handleSubmit(e) {
    e.preventDefault();

    // Frontend validation (instant feedback)
    const validationErrors = validate();
    if (Object.keys(validationErrors).length > 0) {
      setErrors(validationErrors);
      return;
    }

    setErrors({});
    setSubmitting(true);

    try {
      const newUser = await createUser(formData);
      onUserCreated(newUser);
      setFormData({ name: "", email: "" });
    } catch (err) {
      // Backend validation error (e.g., duplicate email)
      if (err.fieldErrors) {
        setErrors(err.fieldErrors);
      } else {
        setErrors({ general: err.message });
      }
    } finally {
      setSubmitting(false);
    }
  }

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
    if (errors[name]) setErrors(prev => ({ ...prev, [name]: null }));
  }

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input name="name" value={formData.name} onChange={handleChange} placeholder="Name" />
        {errors.name && <p className="error">{errors.name}</p>}
      </div>
      <div>
        <input name="email" value={formData.email} onChange={handleChange} placeholder="Email" />
        {errors.email && <p className="error">{errors.email}</p>}
      </div>

      {errors.general && <p className="error">{errors.general}</p>}

      <button type="submit" disabled={submitting}>
        {submitting ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}
```

Two layers of validation:

1. **Frontend** — catches missing fields before sending the request (instant)
2. **Backend** — catches things like duplicate emails (requires API call)

<Tip>
  Clear field errors when the user starts typing in that field. This gives immediate feedback that they're fixing the issue. The `handleChange` function checks `if (errors[name])` to do this.
</Tip>

## The data flow

```
1. User fills out form and clicks "Create"
2. Frontend validates → shows errors OR continues
3. fetch() sends POST /api/users with JSON body
4. FastAPI validates with Pydantic → returns 422 OR continues
5. Backend creates record → returns 201 + new user object
6. Frontend receives new user → calls onUserCreated(newUser)
7. Parent adds to state → React re-renders the list
```

Every step has error handling. The user always knows what happened.

## What's next?

You can create records. Now let's display them — fetching a list from the API and rendering it in React.

<Card title="Read operation" icon="eye" href="/full-stack/read-operation">
  Fetch and display data from your FastAPI backend in React components
</Card>


# Delete operation
Source: https://js.maxbraglia.com/full-stack/delete-operation

Remove records with confirmation and proper error handling

## Always confirm first

Deletion is the one operation you can't undo. Always ask the user to confirm before deleting.

<Tabs>
  <Tab title="Backend (Python)">
    ```python theme={null}
    @app.delete("/api/users/{user_id}", status_code=204)
    def delete_user(user_id: int):
        user = find_user(user_id)
        if not user:
            raise HTTPException(status_code=404, detail="User not found")
        users.remove(user)
        # Returns nothing (204 No Content)
    ```
  </Tab>

  <Tab title="API Client (JS)">
    ```jsx theme={null}
    export async function deleteUser(id) {
      const response = await fetch(`${API_URL}/api/users/${id}`, {
        method: "DELETE",
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
    }
    ```
  </Tab>
</Tabs>

## Simple confirmation with window\.confirm

The quickest approach — a browser-native confirmation dialog:

```jsx theme={null}
function UserCard({ user, onDelete }) {
  const [deleting, setDeleting] = useState(false);

  async function handleDelete() {
    if (!window.confirm(`Delete ${user.name}? This can't be undone.`)) {
      return; // User clicked Cancel
    }

    setDeleting(true);
    try {
      await deleteUser(user.id);
      onDelete(user.id);
    } catch (err) {
      alert(`Failed to delete: ${err.message}`);
    } finally {
      setDeleting(false);
    }
  }

  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
      <button onClick={handleDelete} disabled={deleting}>
        {deleting ? "Deleting..." : "Delete"}
      </button>
    </div>
  );
}
```

`window.confirm()` is perfectly fine for admin tools and internal apps. It's ugly but it works.

## Custom confirmation UI

For a better user experience, build your own confirmation:

```jsx theme={null}
function UserCard({ user, onDelete }) {
  const [confirming, setConfirming] = useState(false);
  const [deleting, setDeleting] = useState(false);
  const [error, setError] = useState(null);

  async function handleConfirmedDelete() {
    setDeleting(true);
    setError(null);

    try {
      await deleteUser(user.id);
      onDelete(user.id);
    } catch (err) {
      setError(err.message);
      setConfirming(false);
    } finally {
      setDeleting(false);
    }
  }

  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>

      {error && <p className="error">{error}</p>}

      {confirming ? (
        <div className="confirm-delete">
          <p>Delete {user.name}?</p>
          <button
            onClick={handleConfirmedDelete}
            disabled={deleting}
            className="btn-danger"
          >
            {deleting ? "Deleting..." : "Yes, delete"}
          </button>
          <button onClick={() => setConfirming(false)}>
            Cancel
          </button>
        </div>
      ) : (
        <button onClick={() => setConfirming(true)}>
          Delete
        </button>
      )}
    </div>
  );
}
```

Two states: `confirming` (are we showing the confirmation?) and `deleting` (is the API call in progress?). The user clicks Delete → sees "Yes, delete" / "Cancel" → confirms → item is removed.

## Updating the parent's state

The parent removes the deleted item from its list:

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);

  function handleDelete(userId) {
    setUsers(prev => prev.filter(u => u.id !== userId));
  }

  return (
    <div>
      {users.map(user => (
        <UserCard
          key={user.id}
          user={user}
          onDelete={handleDelete}
        />
      ))}
    </div>
  );
}
```

`.filter()` creates a new array without the deleted item. This is the standard pattern for removing items from a list in React.

<Info>
  `prev.filter(u => u.id !== userId)` keeps every user whose ID does NOT match the deleted one. Simple, immutable, and correct. You'll use this pattern alongside `.map()` for updates and `[...prev, newItem]` for creates.
</Info>

## The three state update patterns

You now have all the CRUD state updates:

```jsx theme={null}
// CREATE — add to the end
setUsers(prev => [...prev, newUser]);

// UPDATE — replace the matching item
setUsers(prev => prev.map(u => u.id === updated.id ? updated : u));

// DELETE — remove the matching item
setUsers(prev => prev.filter(u => u.id !== userId));
```

These three lines are the entire state management for a CRUD application. Memorize them — you'll write them in every project.

<Tip>
  All three patterns create new arrays instead of modifying the existing one. This is immutable state updates — React requires this to detect changes and re-render. Never use `.push()`, `.splice()`, or direct assignment on state arrays.
</Tip>

## What's next?

You've built all four CRUD operations. Now let's see the complete picture — a full example with everything wired together from backend to frontend.

<Card title="Full example walkthrough" icon="code" href="/full-stack/full-example-walkthrough">
  See a complete CRUD application with React and FastAPI working together
</Card>


# Environment variables
Source: https://js.maxbraglia.com/full-stack/environment-variables

Manage configuration and secrets across development and production

## Don't hardcode URLs

In the previous lesson, the frontend had `http://localhost:8000` hardcoded. This breaks the moment you deploy — your production API isn't at localhost. Environment variables let you configure these values per environment.

```jsx theme={null}
// ❌ Hardcoded — only works locally
fetch("http://localhost:8000/api/users")

// ✅ Environment variable — works everywhere
fetch(`${import.meta.env.VITE_API_BASE_URL}/api/users`)
```

## .env files

An `.env` file stores key-value pairs that your application reads at startup:

```bash theme={null}
# frontend/.env
VITE_API_BASE_URL=http://localhost:8000
```

```bash theme={null}
# backend/.env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SECRET_KEY=your-secret-key-here
```

Each line is `KEY=VALUE`. No spaces around the `=`. No quotes needed (unless the value contains spaces).

<Warning>
  Never commit `.env` files to Git. They contain secrets like database passwords and API keys. Add `.env` to your `.gitignore` file. Always.
</Warning>

## Vite environment variables (frontend)

Vite has one important rule: **frontend environment variables must start with `VITE_`**.

```bash theme={null}
# frontend/.env
VITE_API_BASE_URL=http://localhost:8000
VITE_APP_NAME=My App

# ❌ This WON'T be available in your React code
SECRET_KEY=abc123
```

Access them in your React code with `import.meta.env`:

```jsx theme={null}
// ✅ Available — starts with VITE_
console.log(import.meta.env.VITE_API_BASE_URL);
// "http://localhost:8000"

// ❌ Undefined — doesn't start with VITE_
console.log(import.meta.env.SECRET_KEY);
// undefined
```

<Info>
  The `VITE_` prefix is a security feature. Your React code gets bundled and sent to the user's browser — anyone can read it. The prefix prevents you from accidentally exposing secrets like `DATABASE_URL` or `SECRET_KEY` in your frontend bundle. Only variables you explicitly mark with `VITE_` are included.
</Info>

## Using environment variables in React

```jsx theme={null}
// frontend/src/api/users.js
const API_URL = import.meta.env.VITE_API_BASE_URL;

export async function getUsers() {
  const response = await fetch(`${API_URL}/api/users`);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

export async function createUser(userData) {
  const response = await fetch(`${API_URL}/api/users`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(userData),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}
```

Define the URL once, use it everywhere. When you deploy, just change the environment variable — no code changes needed.

## Python environment variables (backend)

In Python, you already know this pattern. Use `python-dotenv` or Pydantic's `BaseSettings`:

```python theme={null}
# backend/.env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SECRET_KEY=your-secret-key-here
ALLOWED_ORIGINS=http://localhost:5173
```

```python theme={null}
# backend/config.py
import os
from dotenv import load_dotenv

load_dotenv()

DATABASE_URL = os.getenv("DATABASE_URL")
SECRET_KEY = os.getenv("SECRET_KEY")
ALLOWED_ORIGINS = os.getenv("ALLOWED_ORIGINS", "http://localhost:5173").split(",")
```

## .env.example — document what's needed

Create a `.env.example` file that shows what variables are required, without the actual values:

```bash theme={null}
# frontend/.env.example
VITE_API_BASE_URL=http://localhost:8000
```

```bash theme={null}
# backend/.env.example
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SECRET_KEY=change-me-to-a-random-string
ALLOWED_ORIGINS=http://localhost:5173
```

Commit `.env.example` to Git. When a new developer clones the project, they copy it to `.env` and fill in their values:

```bash theme={null}
cp .env.example .env
```

<Tip>
  This is a universal pattern across all frameworks and languages. Every professional project has `.env.example` committed and `.env` in `.gitignore`. It documents what configuration a project needs without exposing secrets.
</Tip>

## Multiple environments

You can have different `.env` files for different situations:

```bash theme={null}
# frontend/.env                 # Default (development)
VITE_API_BASE_URL=http://localhost:8000

# frontend/.env.production      # Used when building for production
VITE_API_BASE_URL=https://api.myapp.com
```

Vite automatically loads the right file:

* `npm run dev` → reads `.env`
* `npm run build` → reads `.env.production` (if it exists)

<Info>
  The companion repo uses `VITE_API_BASE_URL` (same concept, more explicit name). Its mobile app uses Expo's equivalent prefix: `EXPO_PUBLIC_API_BASE_URL`.
</Info>

## What's next?

Your URLs are configurable. But when your React frontend at `localhost:5173` tries to call your FastAPI backend at `localhost:8000`, the browser blocks the request. This is CORS — and it's the most common error when connecting frontend to backend.

<Card title="Understanding CORS" icon="shield" href="/full-stack/understanding-cors">
  Fix cross-origin errors when your React frontend talks to your FastAPI backend
</Card>


# Error handling across the stack
Source: https://js.maxbraglia.com/full-stack/error-handling-stack

Handle errors consistently from FastAPI to React for a great user experience

## Errors happen everywhere

In a full-stack app, errors can occur at every layer:

```
User action
  → Frontend validation error     (missing field)
  → Network error                 (server down, no internet)
  → Backend validation error      (invalid email format)
  → Backend business logic error  (duplicate email)
  → Database error                (connection timeout)
```

Good error handling means the user always sees a clear, helpful message — regardless of where the error originated.

## Layer 1: Backend errors (FastAPI)

FastAPI provides structured error responses. Use `HTTPException` for expected errors:

```python theme={null}
from fastapi import HTTPException

@app.post("/api/users", status_code=201)
def create_user(data: UserCreate):
    # Business logic error
    if any(u["email"] == data.email for u in users):
        raise HTTPException(
            status_code=409,
            detail="A user with this email already exists"
        )

    new_user = save_user(data)
    return new_user

@app.get("/api/users/{user_id}")
def get_user(user_id: int):
    user = find_user(user_id)
    if not user:
        raise HTTPException(
            status_code=404,
            detail="User not found"
        )
    return user
```

Pydantic handles validation errors automatically. If someone sends `{ "name": 123 }` instead of a string, FastAPI returns a 422 with details — you don't need to code this.

### Common HTTP status codes for errors

| Code | Meaning               | When to use                          |
| ---- | --------------------- | ------------------------------------ |
| 400  | Bad Request           | Malformed request                    |
| 404  | Not Found             | Resource doesn't exist               |
| 409  | Conflict              | Duplicate (email already taken)      |
| 422  | Validation Error      | Invalid data (Pydantic handles this) |
| 500  | Internal Server Error | Unexpected bug on the server         |

<Tip>
  Write clear `detail` messages. They travel all the way to the user's screen. "A user with this email already exists" is better than "Conflict" or "Error 409".
</Tip>

## Layer 2: API client (JavaScript)

Your API client translates HTTP errors into JavaScript errors:

```jsx theme={null}
// frontend/src/api/client.js
const API_URL = import.meta.env.VITE_API_BASE_URL;

export async function apiClient(endpoint, options = {}) {
  let response;

  try {
    response = await fetch(`${API_URL}${endpoint}`, {
      headers: { "Content-Type": "application/json", ...options.headers },
      ...options,
    });
  } catch (err) {
    // Network error — server is down, no internet, CORS issue
    throw new Error("Unable to connect to the server. Please check your connection.");
  }

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));

    // FastAPI validation errors (422)
    if (response.status === 422 && Array.isArray(errorData.detail)) {
      const fieldErrors = {};
      for (const err of errorData.detail) {
        const field = err.loc[err.loc.length - 1];
        fieldErrors[field] = err.msg;
      }
      const error = new Error("Please fix the highlighted fields");
      error.fieldErrors = fieldErrors;
      throw error;
    }

    // All other errors — use the backend's message
    throw new Error(errorData.detail || `Something went wrong (HTTP ${response.status})`);
  }

  if (response.status === 204) return null;
  return response.json();
}
```

This handles three types of errors:

1. **Network errors** — `fetch()` itself throws (no response at all)
2. **Validation errors** — 422 with field-level details from Pydantic
3. **Other HTTP errors** — 404, 409, 500, etc. with `detail` message from FastAPI

## Layer 3: React components

Components catch errors and display them to the user:

```jsx theme={null}
function CreateUserForm({ onSubmit }) {
  const [formData, setFormData] = useState({ name: "", email: "" });
  const [errors, setErrors] = useState({});       // Field-level errors
  const [globalError, setGlobalError] = useState(null); // General errors
  const [submitting, setSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault();
    setErrors({});
    setGlobalError(null);
    setSubmitting(true);

    try {
      await onSubmit(formData);
      setFormData({ name: "", email: "" });
    } catch (err) {
      if (err.fieldErrors) {
        // Validation errors → show next to each field
        setErrors(err.fieldErrors);
      } else {
        // Network/server errors → show at the top
        setGlobalError(err.message);
      }
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {globalError && (
        <div className="error-banner">{globalError}</div>
      )}

      <div>
        <input name="name" value={formData.name} onChange={...} />
        {errors.name && <p className="field-error">{errors.name}</p>}
      </div>

      <div>
        <input name="email" value={formData.email} onChange={...} />
        {errors.email && <p className="field-error">{errors.email}</p>}
      </div>

      <button disabled={submitting}>
        {submitting ? "Saving..." : "Save"}
      </button>
    </form>
  );
}
```

Two error display zones:

* **Global errors** (top of form) — network errors, server errors, unexpected issues
* **Field errors** (next to inputs) — validation errors for specific fields

## Page-level error handling

For data fetching errors, use the early return pattern:

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  async function loadUsers() {
    try {
      setLoading(true);
      setError(null);
      const data = await getUsers();
      setUsers(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => { loadUsers(); }, []);

  if (loading) return <p>Loading...</p>;

  if (error) {
    return (
      <div className="error-page">
        <h2>Something went wrong</h2>
        <p>{error}</p>
        <button onClick={loadUsers}>Try Again</button>
      </div>
    );
  }

  return (
    <div>
      <h1>Users</h1>
      {/* ... */}
    </div>
  );
}
```

<Info>
  The "Try Again" button calls `loadUsers()` directly. It resets the error, shows loading, and retries the fetch. Simple and effective.
</Info>

## The error flow — from backend to user

```
FastAPI raises HTTPException(status_code=409, detail="Email already exists")
  ↓
HTTP response: { "detail": "Email already exists" } with status 409
  ↓
apiClient() reads response, throws new Error("Email already exists")
  ↓
Component catches error, calls setGlobalError("Email already exists")
  ↓
User sees: "Email already exists" on screen
```

The `detail` message you write in Python shows up directly on the user's screen. Write it for humans, not for developers.

## Error handling checklist

Every component that makes API calls should handle:

* [ ] **Network failures** — "Unable to connect" message with retry option
* [ ] **Validation errors** — field-level messages next to inputs
* [ ] **Not found (404)** — "Record not found" message
* [ ] **Conflict (409)** — "Already exists" message
* [ ] **Server errors (500)** — "Something went wrong" with retry option
* [ ] **Loading state** — disable buttons, show spinners during requests

<Warning>
  Never show raw error messages like "HTTP 500" or stack traces to users. Always translate technical errors into human-readable messages. The API client is the right place to do this translation.
</Warning>

## What's next?

Errors are handled. The last piece of polish: loading states throughout your app — spinners, skeleton screens, and disabled buttons that make your app feel professional.

<Card title="Loading states everywhere" icon="spinner" href="/full-stack/loading-states-everywhere">
  Provide consistent loading feedback throughout your full-stack application
</Card>


# Full example walkthrough
Source: https://js.maxbraglia.com/full-stack/full-example-walkthrough

See a complete CRUD application with React and FastAPI working together

## The complete app

Let's put everything together. This is a complete user management app — the same patterns you've learned across the last several lessons, wired together into one working application.

<Info>
  This walkthrough is a **JS-first teaching version** of the patterns. The companion repo is more production-structured: backend routes live in `backend/routers/users.py`, models in `backend/models.py`, the web client is TypeScript (`.ts/.tsx` with `frontend/src/types.ts` and `frontend/src/api/users.ts`), and there's also a `mobile/` Expo app using the same FastAPI API.
</Info>

```
my-fullstack-app/
├── backend/
│   └── main.py              # FastAPI — all endpoints
├── frontend/
│   └── src/
│       ├── api/
│       │   ├── client.js     # Shared fetch helper
│       │   └── users.js      # User CRUD functions
│       ├── components/
│       │   ├── CreateUserForm.jsx
│       │   ├── EditUserForm.jsx
│       │   └── UserCard.jsx
│       ├── App.jsx           # Main page component
│       └── main.jsx          # Entry point
```

## Backend — the full API

<Info>
  The companion repo uses `UserCreate` for both create and update. This walkthrough shows a separate `UserUpdate` model to demonstrate a common partial-update pattern you'll likely adopt later.
</Info>

```python theme={null}
# backend/main.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import os

app = FastAPI()

ALLOWED_ORIGINS = os.getenv("ALLOWED_ORIGINS", "http://localhost:5173").split(",")

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# ── Models ──────────────────────────────────────

class UserCreate(BaseModel):
    name: str
    email: str

class UserUpdate(BaseModel):
    name: str | None = None
    email: str | None = None

# ── In-memory storage (use a real DB in production) ──

users = [
    {"id": 1, "name": "Sarah Chen", "email": "sarah@example.com"},
    {"id": 2, "name": "John Park", "email": "john@example.com"},
]
next_id = 3

def find_user(user_id: int):
    return next((u for u in users if u["id"] == user_id), None)

# ── Endpoints ───────────────────────────────────

@app.get("/api/users")
def get_users():
    return users

@app.get("/api/users/{user_id}")
def get_user(user_id: int):
    user = find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@app.post("/api/users", status_code=201)
def create_user(data: UserCreate):
    global next_id
    new_user = {"id": next_id, "name": data.name, "email": data.email}
    users.append(new_user)
    next_id += 1
    return new_user

@app.put("/api/users/{user_id}")
def update_user(user_id: int, data: UserUpdate):
    user = find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    if data.name is not None:
        user["name"] = data.name
    if data.email is not None:
        user["email"] = data.email
    return user

@app.delete("/api/users/{user_id}", status_code=204)
def delete_user(user_id: int):
    user = find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    users.remove(user)
```

Five endpoints. Five HTTP methods. That's the entire backend for a CRUD app.

## Frontend — the API client

```jsx theme={null}
// frontend/src/api/client.js
const API_URL = import.meta.env.VITE_API_BASE_URL;

export async function apiClient(endpoint, options = {}) {
  const response = await fetch(`${API_URL}${endpoint}`, {
    headers: {
      "Content-Type": "application/json",
      ...options.headers,
    },
    ...options,
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail || `HTTP ${response.status}`);
  }

  if (response.status === 204) return null;
  return response.json();
}
```

```jsx theme={null}
// frontend/src/api/users.js
import { apiClient } from './client';

export const getUsers    = ()         => apiClient("/api/users");
export const getUser     = (id)       => apiClient(`/api/users/${id}`);
export const createUser  = (data)     => apiClient("/api/users", { method: "POST", body: JSON.stringify(data) });
export const updateUser  = (id, data) => apiClient(`/api/users/${id}`, { method: "PUT", body: JSON.stringify(data) });
export const deleteUser  = (id)       => apiClient(`/api/users/${id}`, { method: "DELETE" });
```

## Frontend — the components

```jsx theme={null}
// frontend/src/components/CreateUserForm.jsx
import { useState } from 'react';

export default function CreateUserForm({ onSubmit }) {
  const [formData, setFormData] = useState({ name: "", email: "" });
  const [submitting, setSubmitting] = useState(false);
  const [error, setError] = useState(null);

  function handleChange(e) {
    setFormData(prev => ({ ...prev, [e.target.name]: e.target.value }));
  }

  async function handleSubmit(e) {
    e.preventDefault();
    setSubmitting(true);
    setError(null);
    try {
      await onSubmit(formData);
      setFormData({ name: "", email: "" });
    } catch (err) {
      setError(err.message);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={formData.name} onChange={handleChange} placeholder="Name" required />
      <input name="email" type="email" value={formData.email} onChange={handleChange} placeholder="Email" required />
      {error && <p className="error">{error}</p>}
      <button disabled={submitting}>{submitting ? "Adding..." : "Add User"}</button>
    </form>
  );
}
```

```jsx theme={null}
// frontend/src/components/EditUserForm.jsx
import { useState } from 'react';

export default function EditUserForm({ user, onSave, onCancel }) {
  const [formData, setFormData] = useState({ name: user.name, email: user.email });
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState(null);

  function handleChange(e) {
    setFormData(prev => ({ ...prev, [e.target.name]: e.target.value }));
  }

  async function handleSubmit(e) {
    e.preventDefault();
    setSaving(true);
    setError(null);
    try {
      await onSave(formData);
    } catch (err) {
      setError(err.message);
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={formData.name} onChange={handleChange} required />
      <input name="email" type="email" value={formData.email} onChange={handleChange} required />
      {error && <p className="error">{error}</p>}
      <button disabled={saving}>{saving ? "Saving..." : "Save"}</button>
      <button type="button" onClick={onCancel}>Cancel</button>
    </form>
  );
}
```

```jsx theme={null}
// frontend/src/components/UserCard.jsx
import { useState } from 'react';
import EditUserForm from './EditUserForm';

export default function UserCard({ user, onUpdate, onDelete }) {
  const [editing, setEditing] = useState(false);
  const [deleting, setDeleting] = useState(false);

  async function handleSave(formData) {
    const updated = await onUpdate(user.id, formData);
    setEditing(false);
    return updated;
  }

  async function handleDelete() {
    if (!window.confirm(`Delete ${user.name}?`)) return;
    setDeleting(true);
    try {
      await onDelete(user.id);
    } catch {
      setDeleting(false);
    }
  }

  if (editing) {
    return <EditUserForm user={user} onSave={handleSave} onCancel={() => setEditing(false)} />;
  }

  return (
    <div className="user-card">
      <strong>{user.name}</strong> — {user.email}
      <button onClick={() => setEditing(true)}>Edit</button>
      <button onClick={handleDelete} disabled={deleting}>
        {deleting ? "..." : "Delete"}
      </button>
    </div>
  );
}
```

## Frontend — the main page

```jsx theme={null}
// frontend/src/App.jsx
import { useState, useEffect } from 'react';
import { getUsers, createUser, updateUser, deleteUser } from './api/users';
import CreateUserForm from './components/CreateUserForm';
import UserCard from './components/UserCard';

export default function App() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    getUsers()
      .then(data => setUsers(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  async function handleCreate(formData) {
    const newUser = await createUser(formData);
    setUsers(prev => [...prev, newUser]);
  }

  async function handleUpdate(userId, formData) {
    const updated = await updateUser(userId, formData);
    setUsers(prev => prev.map(u => u.id === userId ? updated : u));
    return updated;
  }

  async function handleDelete(userId) {
    await deleteUser(userId);
    setUsers(prev => prev.filter(u => u.id !== userId));
  }

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

  return (
    <div>
      <h1>User Management</h1>

      <h2>Add User</h2>
      <CreateUserForm onSubmit={handleCreate} />

      <h2>Users ({users.length})</h2>
      {users.length === 0 ? (
        <p>No users yet. Add one above!</p>
      ) : (
        users.map(user => (
          <UserCard
            key={user.id}
            user={user}
            onUpdate={handleUpdate}
            onDelete={handleDelete}
          />
        ))
      )}
    </div>
  );
}
```

## Tracing the data flow

Let's trace what happens when a user clicks "Add User":

<Steps>
  <Step title="User fills form and submits">
    `CreateUserForm` calls `onSubmit({ name: "Maria Lopez", email: "maria@example.com" })`
  </Step>

  <Step title="App.jsx handles the create">
    `handleCreate` calls `createUser(formData)` from the API client
  </Step>

  <Step title="API client sends the request">
    `fetch("http://localhost:8000/api/users", { method: "POST", body: ... })`
  </Step>

  <Step title="FastAPI receives and validates">
    Pydantic validates the data. If valid, creates the user and returns `{ id: 3, name: "Maria Lopez", email: "maria@example.com" }` with status 201
  </Step>

  <Step title="API client parses the response">
    `response.json()` returns the new user object back to `handleCreate`
  </Step>

  <Step title="State updates, React re-renders">
    `setUsers(prev => [...prev, newUser])` adds the user. React re-renders the list. Maria appears on screen.
  </Step>
</Steps>

Every CRUD operation follows this same flow: Component → API client → `fetch()` → FastAPI → response → state update → re-render.

<Tip>
  When debugging, trace the flow step by step. Add `console.log` at each stage to see where data gets lost or transformed incorrectly. The Network tab in DevTools shows the actual HTTP requests and responses.
</Tip>

## What's next?

You've seen the complete app. Now let's polish it — handling errors gracefully across the entire stack.

<Card title="Error handling across the stack" icon="triangle-exclamation" href="/full-stack/error-handling-stack">
  Handle errors consistently from FastAPI to React for a great user experience
</Card>


# Loading states everywhere
Source: https://js.maxbraglia.com/full-stack/loading-states-everywhere

Provide consistent loading feedback throughout your full-stack application

## The user should never wonder "is it working?"

Every time your app talks to the API, the user should see feedback. No feedback = "is it broken?" Feedback = "it's working." This is the difference between an app that feels amateur and one that feels professional.

## Page-level loading

When a page loads data for the first time, show a full-page loading state:

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    getUsers()
      .then(data => setUsers(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  if (loading) {
    return (
      <div className="page-loading">
        <div className="spinner"></div>
        <p>Loading users...</p>
      </div>
    );
  }

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

  return (
    <div>
      <h1>Users ({users.length})</h1>
      {/* ... */}
    </div>
  );
}
```

A simple CSS spinner:

```css theme={null}
.spinner {
  width: 32px;
  height: 32px;
  border: 3px solid #e5e7eb;
  border-top-color: #3b82f6;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}

.page-loading {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 4rem;
  gap: 1rem;
}
```

## Button loading states

Disable buttons and show feedback during API calls:

```jsx theme={null}
function CreateUserForm({ onSubmit }) {
  const [submitting, setSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault();
    setSubmitting(true);
    try {
      await onSubmit(formData);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... inputs ... */}
      <button type="submit" disabled={submitting}>
        {submitting ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}
```

The button tells the user three things:

1. **Before click**: "Create User" — here's what this does
2. **During API call**: "Creating..." + disabled — your request is being processed
3. **After completion**: back to "Create User" — ready for the next action

<Tip>
  Always disable buttons during API calls. This prevents double submissions — clicking "Create User" twice would create two users. The `disabled` attribute stops the second click.
</Tip>

## Delete button with loading

```jsx theme={null}
function DeleteButton({ onDelete, label = "Delete" }) {
  const [deleting, setDeleting] = useState(false);

  async function handleClick() {
    if (!window.confirm("Are you sure?")) return;
    setDeleting(true);
    try {
      await onDelete();
    } catch {
      setDeleting(false); // Reset on error so user can retry
    }
  }

  return (
    <button onClick={handleClick} disabled={deleting} className="btn-danger">
      {deleting ? "Deleting..." : label}
    </button>
  );
}
```

## Inline loading for updates

When editing a single item in a list, show loading on that item only — not the whole page:

```jsx theme={null}
function UserCard({ user, onUpdate, onDelete }) {
  const [editing, setEditing] = useState(false);
  const [saving, setSaving] = useState(false);
  const [deleting, setDeleting] = useState(false);

  async function handleSave(formData) {
    setSaving(true);
    try {
      await onUpdate(user.id, formData);
      setEditing(false);
    } finally {
      setSaving(false);
    }
  }

  return (
    <div className={`user-card ${saving || deleting ? "loading" : ""}`}>
      {editing ? (
        <EditForm user={user} onSave={handleSave} saving={saving} />
      ) : (
        <>
          <span>{user.name} — {user.email}</span>
          <button onClick={() => setEditing(true)}>Edit</button>
          <button onClick={handleDelete} disabled={deleting}>
            {deleting ? "..." : "Delete"}
          </button>
        </>
      )}
    </div>
  );
}
```

```css theme={null}
.user-card.loading {
  opacity: 0.6;
  pointer-events: none;
}
```

The subtle opacity change tells users "this item is being updated" without blocking the entire page.

## Skeleton screens

For a polished feel, show placeholder shapes instead of a spinner:

```jsx theme={null}
function UserCardSkeleton() {
  return (
    <div className="user-card skeleton">
      <div className="skeleton-line skeleton-name"></div>
      <div className="skeleton-line skeleton-email"></div>
    </div>
  );
}

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  // ... fetch users ...

  if (loading) {
    return (
      <div>
        <UserCardSkeleton />
        <UserCardSkeleton />
        <UserCardSkeleton />
      </div>
    );
  }

  return (
    <div>
      {users.map(user => <UserCard key={user.id} user={user} />)}
    </div>
  );
}
```

```css theme={null}
.skeleton-line {
  height: 16px;
  background: linear-gradient(90deg, #e5e7eb 25%, #f3f4f6 50%, #e5e7eb 75%);
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
  border-radius: 4px;
}

.skeleton-name { width: 40%; margin-bottom: 8px; }
.skeleton-email { width: 60%; }

@keyframes shimmer {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}
```

<Info>
  Skeleton screens feel faster than spinners because they show the layout of what's coming. The user's brain starts processing the structure before data arrives. Use skeletons for lists and cards, spinners for simple operations.
</Info>

## A reusable loading pattern

Wrap the loading/error/data pattern into a reusable component:

```jsx theme={null}
function AsyncContent({ loading, error, onRetry, children, empty, emptyMessage = "No data" }) {
  if (loading) {
    return (
      <div className="page-loading">
        <div className="spinner"></div>
      </div>
    );
  }

  if (error) {
    return (
      <div className="error-state">
        <p>{error}</p>
        {onRetry && <button onClick={onRetry}>Try Again</button>}
      </div>
    );
  }

  if (empty) {
    return <p className="empty-state">{emptyMessage}</p>;
  }

  return children;
}
```

```jsx theme={null}
// Usage — much cleaner
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // ... fetch logic ...

  return (
    <div>
      <h1>Users</h1>
      <AsyncContent
        loading={loading}
        error={error}
        onRetry={loadUsers}
        empty={users.length === 0}
        emptyMessage="No users yet. Create one above!"
      >
        {users.map(user => (
          <UserCard key={user.id} user={user} />
        ))}
      </AsyncContent>
    </div>
  );
}
```

## Loading state checklist

| Action          | Loading indicator               | Where                 |
| --------------- | ------------------------------- | --------------------- |
| Page first load | Spinner or skeleton             | Replace page content  |
| Form submit     | "Saving..." + disabled button   | The submit button     |
| Delete          | "Deleting..." + disabled button | The delete button     |
| Inline edit     | Opacity + disabled              | The item being edited |
| Search/filter   | (instant, no loading needed)    | Client-side filtering |

<Tip>
  The rule is simple: every API call needs loading feedback. If a user clicks something and nothing visibly happens for even half a second, add a loading state. Users will assume it's broken if they don't see immediate feedback.
</Tip>

## What's next?

Congratulations — you've built a complete full-stack application with React and FastAPI. You have CRUD operations, error handling, loading states, and professional UX patterns.

Now let's wrap up the course and prepare you for what comes next.

<Card title="Course wrap-up" icon="graduation-cap" href="/next-steps/course-wrap-up">
  Review what you've learned and where to go from here
</Card>


# Project structure
Source: https://js.maxbraglia.com/full-stack/project-structure

Organize your full-stack project with separate frontend and backend folders

## Two apps, one project

A full-stack app is two separate applications that talk to each other: a **React frontend** (what users see) and a **FastAPI backend** (your API and database). They run independently, communicate over HTTP, and live in separate folders.

<Info>
  This lesson uses a simplified JS-first structure to teach the pattern clearly. The companion repo uses a more production-style layout: `backend/main.py` + `backend/routers/users.py` + `backend/models.py` + `backend/database.py`, a TypeScript web frontend (`.tsx`/`.ts`), and a `mobile/` Expo app that uses the same API.
</Info>

```
my-fullstack-app/
├── backend/                # FastAPI (Python)
│   ├── main.py             # FastAPI app, routes
│   ├── models.py           # Pydantic models
│   ├── database.py         # Database connection
│   ├── requirements.txt    # Python dependencies
│   ├── .env                # Backend secrets (DB URL, API keys)
│   └── venv/               # Python virtual environment
│
├── frontend/               # React (JavaScript)
│   ├── src/
│   │   ├── App.jsx         # Main component
│   │   ├── main.jsx        # Entry point
│   │   ├── api/            # API client functions
│   │   │   └── users.js    # fetch calls to backend
│   │   ├── components/     # Reusable UI components
│   │   │   ├── UserCard.jsx
│   │   │   ├── UserForm.jsx
│   │   │   └── Spinner.jsx
│   │   └── pages/          # Page-level components
│   │       └── Dashboard.jsx
│   ├── .env                # Frontend config (API URL)
│   ├── package.json        # JS dependencies
│   └── vite.config.js      # Vite configuration
│
├── .gitignore
└── README.md
```

This is the standard structure. You'll see it in almost every full-stack project.

## The backend (FastAPI)

Your FastAPI backend is a Python project you already know how to build. Here's the minimum:

```python theme={null}
# backend/main.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel

app = FastAPI()

# Allow React frontend to make requests (more on CORS later)
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# In-memory storage (use a real database in production)
users = []
next_id = 1

class UserCreate(BaseModel):
    name: str
    email: str

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/api/users")
def get_users():
    return users

@app.get("/api/users/{user_id}")
def get_user(user_id: int):
    for user in users:
        if user["id"] == user_id:
            return user
    raise HTTPException(status_code=404, detail="User not found")

@app.post("/api/users", status_code=201)
def create_user(user: UserCreate):
    global next_id
    new_user = {"id": next_id, "name": user.name, "email": user.email}
    users.append(new_user)
    next_id += 1
    return new_user
```

```bash theme={null}
# Run the backend
cd backend
pip install fastapi uvicorn
uvicorn main:app --reload --port 8000
```

<Tip>
  In the companion repo, the backend uses `uv` with `pyproject.toml`, so the command is `uv run fastapi dev main.py` instead of `uvicorn main:app --reload`.
</Tip>

Your API is now running at `http://localhost:8000`. You can test it at `http://localhost:8000/docs` (FastAPI's built-in Swagger UI).

## The frontend (React)

Your React frontend is a Vite project that fetches data from the backend:

```bash theme={null}
# Create the frontend
cd my-fullstack-app
npm create vite@latest frontend -- --template react
cd frontend
npm install
npm run dev
```

React runs at `http://localhost:5173`. It makes `fetch()` calls to `http://localhost:8000/api/...` to get and send data.

```jsx theme={null}
// frontend/src/App.jsx
import { useState, useEffect } from 'react';

function App() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    fetch("http://localhost:8000/api/users")
      .then(r => r.json())
      .then(data => setUsers(data));
  }, []);

  return (
    <div>
      <h1>Users</h1>
      {users.map(user => (
        <p key={user.id}>{user.name} — {user.email}</p>
      ))}
    </div>
  );
}

export default App;
```

<Info>
  The frontend and backend run on different ports (5173 and 8000). They're completely separate applications. The frontend doesn't know or care that the backend is Python — it just makes HTTP requests and gets JSON back.
</Info>

## How they communicate

```
┌─────────────────────┐         HTTP          ┌─────────────────────┐
│   React Frontend    │  ──── requests ────►  │   FastAPI Backend   │
│   localhost:5173    │  ◄── JSON responses ── │   localhost:8000    │
│                     │                        │                     │
│  • Components       │                        │  • Routes           │
│  • State (useState) │                        │  • Pydantic models  │
│  • UI rendering     │                        │  • Database queries  │
└─────────────────────┘                        └─────────────────────┘
```

The frontend uses `fetch()` to make HTTP requests (GET, POST, PUT, DELETE). The backend processes the request and returns JSON. The frontend updates its state with the response and re-renders the UI.

This is the same architecture used by every major web application — Gmail, Twitter, Spotify. The only difference is scale.

## Running both together

During development, you need two terminal windows:

<Tabs>
  <Tab title="Terminal 1 — Backend">
    ```bash theme={null}
    cd backend
    source venv/bin/activate   # Activate Python environment
    uvicorn main:app --reload --port 8000
    ```
  </Tab>

  <Tab title="Terminal 2 — Frontend">
    ```bash theme={null}
    cd frontend
    npm run dev
    ```
  </Tab>
</Tabs>

<Tip>
  Keep both terminals visible. When you see an error in the browser, check both terminals — the bug could be on either side. FastAPI's terminal shows Python errors. Vite's terminal shows JavaScript build errors.
</Tip>

## .gitignore

Make sure you don't commit dependencies or secrets:

```gitignore theme={null}
# Python
backend/venv/
backend/__pycache__/
backend/.env

# JavaScript
frontend/node_modules/
frontend/dist/

# Environment files with secrets
.env
*.env.local

# OS files
.DS_Store
```

## What's next?

Your project is structured. But those hardcoded URLs (`http://localhost:8000`) won't work in production. Let's fix that with environment variables.

<Card title="Environment variables" icon="key" href="/full-stack/environment-variables">
  Manage configuration and secrets across development and production
</Card>


# Read operation
Source: https://js.maxbraglia.com/full-stack/read-operation

Fetch and display data from your FastAPI backend in React components

## Fetching a list on mount

The most common Read operation: load data when a page first appears.

<Tabs>
  <Tab title="Backend (Python)">
    ```python theme={null}
    @app.get("/api/users")
    def get_users():
        return users  # Returns a list of user objects
    ```
  </Tab>

  <Tab title="API Client (JS)">
    ```jsx theme={null}
    // frontend/src/api/users.js
    export async function getUsers() {
      const response = await fetch(`${API_URL}/api/users`);
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return response.json();
    }
    ```
  </Tab>
</Tabs>

## The component — loading, error, data

```jsx theme={null}
import { useState, useEffect } from 'react';
import { getUsers } from '../api/users';

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUsers() {
      try {
        const data = await getUsers();
        setUsers(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []);

  if (loading) return <p>Loading users...</p>;
  if (error) return <p className="error">Error: {error}</p>;
  if (users.length === 0) return <p>No users yet. Create one above!</p>;

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          <strong>{user.name}</strong> — {user.email}
        </li>
      ))}
    </ul>
  );
}
```

Four states handled in order:

1. **Loading** — show a spinner or "Loading..." text
2. **Error** — show what went wrong
3. **Empty** — data loaded but the list is empty
4. **Data** — render the list

This is the pattern you'll use for every page that displays data. It never changes.

## Fetching a single record

For detail pages (e.g., `/users/3`), fetch one record by ID:

<Tabs>
  <Tab title="Backend (Python)">
    ```python theme={null}
    @app.get("/api/users/{user_id}")
    def get_user(user_id: int):
        user = find_user(user_id)
        if not user:
            raise HTTPException(status_code=404, detail="User not found")
        return user
    ```
  </Tab>

  <Tab title="API Client (JS)">
    ```jsx theme={null}
    export async function getUser(id) {
      const response = await fetch(`${API_URL}/api/users/${id}`);
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return response.json();
    }
    ```
  </Tab>
</Tabs>

```jsx theme={null}
function UserDetail({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUser() {
      try {
        const data = await getUser(userId);
        setUser(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUser();
  }, [userId]); // Re-fetch when userId changes

  if (loading) return <p>Loading...</p>;
  if (error) return <p className="error">{error}</p>;
  if (!user) return <p>User not found</p>;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <p>User ID: {user.id}</p>
    </div>
  );
}
```

<Info>
  Notice `[userId]` in the dependency array. If the user navigates from one profile to another, `userId` changes and the effect re-runs — fetching the new user automatically.
</Info>

## Rendering with components

Break the display into reusable components:

```jsx theme={null}
function UserCard({ user }) {
  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </div>
  );
}

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    getUsers()
      .then(data => setUsers(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <Spinner />;
  if (error) return <ErrorMessage message={error} />;
  if (users.length === 0) return <EmptyState message="No users yet" />;

  return (
    <div className="user-grid">
      {users.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}
```

The smart component (`UserList`) handles state and fetching. The presentational component (`UserCard`) just displays data. This is the composition pattern from the React Essentials section.

<Info>
  The companion repo's `User` shape is intentionally simple: `id`, `name`, and `email`. If you add fields later (like `role`), this same read pattern still works — you just render the new properties.
</Info>

## Search and filter

Add client-side filtering to your list:

```jsx theme={null}
function SearchableUserList() {
  const [users, setUsers] = useState([]);
  const [search, setSearch] = useState("");
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    getUsers()
      .then(data => setUsers(data))
      .finally(() => setLoading(false));
  }, []);

  const filtered = users.filter(user =>
    user.name.toLowerCase().includes(search.toLowerCase()) ||
    user.email.toLowerCase().includes(search.toLowerCase())
  );

  if (loading) return <p>Loading...</p>;

  return (
    <div>
      <input
        type="text"
        value={search}
        onChange={e => setSearch(e.target.value)}
        placeholder="Search by name or email..."
      />
      <p>{filtered.length} of {users.length} users</p>
      {filtered.map(user => (
        <UserCard key={user.id} user={user} />
      ))}
    </div>
  );
}
```

Fetch the full list once, then filter in the browser. This is fast for small-to-medium lists (hundreds of items). For large datasets, filter on the backend with query parameters.

<Tip>
  For small datasets (under \~500 items), client-side filtering is simpler and faster — no extra API calls on every keystroke. For large datasets, send the search term as a query parameter: `GET /api/users?search=sarah`.
</Tip>

## Refreshing data

Sometimes you need to reload data — after creating, updating, or deleting:

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  async function loadUsers() {
    setLoading(true);
    try {
      const data = await getUsers();
      setUsers(data);
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => {
    loadUsers();
  }, []);

  async function handleUserCreated(newUser) {
    // Option 1: Add to local state (instant, no extra request)
    setUsers(prev => [...prev, newUser]);

    // Option 2: Refetch the full list (always in sync with backend)
    // await loadUsers();
  }

  return (
    <div>
      <CreateUserForm onUserCreated={handleUserCreated} />
      {loading ? <p>Loading...</p> : (
        <ul>
          {users.map(user => (
            <li key={user.id}>{user.name}</li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

Option 1 (update local state) is faster. Option 2 (refetch) is simpler and always correct. Start with local state updates, and switch to refetching if you run into sync issues.

## What's next?

You can create and read records. Now let's add editing — loading existing data into a form and sending updates back to the API.

<Card title="Update operation" icon="pen" href="/full-stack/update-operation">
  Edit existing records with a form that sends PUT requests to your API
</Card>


# Type safety
Source: https://js.maxbraglia.com/full-stack/type-safety

Ensure your frontend and backend agree on data shapes

## The problem: silent mismatches

Your FastAPI backend defines data shapes with Pydantic models. Your React frontend sends and receives that data. If they disagree on the shape, things break — often silently.

```python theme={null}
# Backend expects this shape
class UserCreate(BaseModel):
    name: str
    email: str
```

```jsx theme={null}
// Frontend sends this — missing "name", has extra "username"
const userData = { username: "Sarah", email: "sarah@example.com" };
await createUser(userData);
// Backend gets { username: "Sarah", email: "..." }
// "name" is missing → 422 Validation Error
// "username" is ignored silently
```

The backend rejects it with a 422 error, but the error message isn't always obvious. Or worse — the frontend reads a field that the backend renamed, and you get `undefined` rendering on screen with no error at all.

## Keep your shapes in sync

The simplest approach: **document the expected shapes in your API client file**.

```jsx theme={null}
// frontend/src/api/users.js

/*
 * User shapes (must match backend Pydantic models):
 *
 * UserCreate: { name: string, email: string }
 * User:       { id: number, name: string, email: string }
 */

import { apiClient } from './client';

export const getUsers = () => apiClient("/api/users");
export const createUser = (data) =>
  apiClient("/api/users", { method: "POST", body: JSON.stringify(data) });
```

This is documentation, not enforcement — but it tells any developer exactly what the backend expects.

## Runtime validation

For critical operations, validate before sending:

```jsx theme={null}
function validateUserData(data) {
  const errors = {};

  if (!data.name || data.name.trim() === "") {
    errors.name = "Name is required";
  }

  if (!data.email || !data.email.includes("@")) {
    errors.email = "Valid email is required";
  }

  return {
    isValid: Object.keys(errors).length === 0,
    errors,
  };
}

// Use before API call
function handleSubmit(formData) {
  const { isValid, errors } = validateUserData(formData);

  if (!isValid) {
    setErrors(errors);
    return;
  }

  createUser(formData); // Only sends if valid
}
```

<Tip>
  Validate on the frontend for instant user feedback. But always validate on the backend too — frontend validation can be bypassed. Pydantic handles backend validation automatically. Think of frontend validation as a UX feature, not a security feature.
</Tip>

## Consistent API response shapes

Design your backend responses to be predictable. When every endpoint follows the same pattern, the frontend code becomes simpler.

```python theme={null}
# Backend — consistent patterns

# List endpoint always returns an array
@app.get("/api/users")
def get_users():
    return users  # Always returns []

# Single item returns the object or 404
@app.get("/api/users/{user_id}")
def get_user(user_id: int):
    user = find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

# Create returns the created object with 201
@app.post("/api/users", status_code=201)
def create_user(user: UserCreate):
    new_user = save_user(user)
    return new_user  # Returns the full object with id

# Update returns the updated object
@app.put("/api/users/{user_id}")
def update_user(user_id: int, user: UserCreate):
    updated = update_user_in_db(user_id, user)
    return updated

# Delete returns nothing with 204
@app.delete("/api/users/{user_id}", status_code=204)
def delete_user(user_id: int):
    remove_user(user_id)
```

The frontend can rely on these patterns:

* **GET list** → always an array (even if empty)
* **GET single** → the object, or a 404 error
* **POST** → returns the created object (with its new `id`)
* **PUT** → returns the updated object
* **DELETE** → returns nothing (204 status)

<Info>
  The companion repo keeps the backend simple and uses `UserCreate` for both create and update operations. A separate `UserUpdate` model (with optional fields) is a common next step once you want partial updates.
</Info>

## Handling backend validation errors

FastAPI returns 422 errors with a structured format. Parse them in your API client:

```jsx theme={null}
// frontend/src/api/client.js
export async function apiClient(endpoint, options = {}) {
  const response = await fetch(`${API_URL}${endpoint}`, {
    headers: { "Content-Type": "application/json", ...options.headers },
    ...options,
  });

  if (!response.ok) {
    const errorData = await response.json().catch(() => ({}));

    // FastAPI 422 validation errors have a specific shape
    if (response.status === 422 && errorData.detail) {
      // Convert FastAPI's validation format to a simple object
      const fieldErrors = {};
      for (const err of errorData.detail) {
        const field = err.loc[err.loc.length - 1]; // Last item is the field name
        fieldErrors[field] = err.msg;
      }
      const error = new Error("Validation failed");
      error.fieldErrors = fieldErrors;
      throw error;
    }

    throw new Error(errorData.detail || `HTTP ${response.status}`);
  }

  if (response.status === 204) return null;
  return response.json();
}
```

```jsx theme={null}
// In your component
async function handleSubmit(formData) {
  try {
    await createUser(formData);
  } catch (err) {
    if (err.fieldErrors) {
      setErrors(err.fieldErrors); // Show per-field errors
    } else {
      setError(err.message); // Show general error
    }
  }
}
```

<Info>
  FastAPI validation errors return an array of `{ loc: ["body", "email"], msg: "field required", type: "missing" }` objects. The code above extracts the field name and message into a simple `{ email: "field required" }` format that your form components can display directly.
</Info>

## TypeScript preview

If you want true compile-time type safety, TypeScript is the answer. Here's a taste:

```tsx theme={null}
// With TypeScript — errors caught before you even run the code
interface User {
  id: number;
  name: string;
  email: string;
}

interface UserCreate {
  name: string;
  email: string;
}

export async function createUser(data: UserCreate): Promise<User> {
  return apiClient("/api/users", {
    method: "POST",
    body: JSON.stringify(data),
  });
}

// ❌ TypeScript error: Property 'username' does not exist on type 'UserCreate'
createUser({ username: "Sarah", email: "sarah@example.com" });
```

TypeScript catches the `username` vs `name` mismatch at development time, before any code runs. This is the gold standard for full-stack type safety.

<Tip>
  You don't need TypeScript to build full-stack apps. JavaScript with good documentation and runtime validation works fine, especially when you're learning. But once you're comfortable with JavaScript, TypeScript is a natural next step — it catches an entire category of bugs automatically.
</Tip>

## What's next?

Your frontend and backend are connected, organized, and type-aware. Now let's build the four CRUD operations that make up every data-driven application — starting with Create.

<Card title="Create operation" icon="plus" href="/full-stack/create-operation">
  Build a form that sends data to your FastAPI backend and creates a new record
</Card>


# Understanding CORS
Source: https://js.maxbraglia.com/full-stack/understanding-cors

Fix cross-origin errors when your React frontend talks to your FastAPI backend

## The error you'll definitely see

The first time your React frontend tries to call your FastAPI backend, you'll see this in the browser console:

```
Access to fetch at 'http://localhost:8000/api/users' from origin
'http://localhost:5173' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource.
```

This is the most common error in full-stack development. It looks scary, but the fix is simple.

## What is CORS?

**CORS** (Cross-Origin Resource Sharing) is a browser security feature. It prevents a website from making requests to a different domain/port unless that server explicitly allows it.

An **origin** is a combination of protocol + domain + port:

| URL                     | Origin                  |
| ----------------------- | ----------------------- |
| `http://localhost:5173` | `http://localhost:5173` |
| `http://localhost:8000` | `http://localhost:8000` |
| `https://myapp.com`     | `https://myapp.com`     |
| `https://api.myapp.com` | `https://api.myapp.com` |

Your React frontend (`localhost:5173`) and your FastAPI backend (`localhost:8000`) have **different origins** because they're on different ports. The browser blocks the request by default.

<Info>
  CORS is a browser-only security feature. It doesn't affect Postman, curl, or server-to-server requests. That's why your API works fine in FastAPI's Swagger UI (`/docs`) or when you test with curl, but breaks when called from React.
</Info>

<Info>
  The companion repo allows more than one dev origin because the same API is used by multiple clients: `http://localhost:5173` (Vite web frontend) and `http://localhost:8081` (Expo web while testing the mobile app).
</Info>

## Why CORS exists

Without CORS, any website could make requests to any other site using your credentials. Imagine visiting a malicious site that silently makes requests to your bank's API using cookies your browser already has stored. CORS prevents this by requiring servers to opt in to receiving requests from other origins.

## The fix: FastAPI CORS middleware

Tell FastAPI to accept requests from your React frontend:

```python theme={null}
# backend/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Add CORS middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # React dev server
    allow_credentials=True,
    allow_methods=["*"],     # Allow all HTTP methods
    allow_headers=["*"],     # Allow all headers
)

# ... your routes below
```

That's it. Add these 7 lines and the CORS error disappears.

### What each option does

| Option              | Value                       | Meaning                                 |
| ------------------- | --------------------------- | --------------------------------------- |
| `allow_origins`     | `["http://localhost:5173"]` | Which frontends can make requests       |
| `allow_credentials` | `True`                      | Allow cookies and auth headers          |
| `allow_methods`     | `["*"]`                     | Allow GET, POST, PUT, DELETE, etc.      |
| `allow_headers`     | `["*"]`                     | Allow Content-Type, Authorization, etc. |

## Development vs production origins

In development, your frontend runs at `localhost:5173`. In production, it runs at your actual domain. Handle both:

```python theme={null}
import os

# Read from environment variable
ALLOWED_ORIGINS = os.getenv(
    "ALLOWED_ORIGINS",
    "http://localhost:5173"
).split(",")

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

```bash theme={null}
# backend/.env (development)
ALLOWED_ORIGINS=http://localhost:5173

# backend/.env (production)
ALLOWED_ORIGINS=https://myapp.com,https://www.myapp.com
```

<Warning>
  Never use `allow_origins=["*"]` in production. This allows any website to call your API — the exact thing CORS was designed to prevent. Always list your specific frontend URL(s).
</Warning>

## How CORS actually works

When your browser makes a cross-origin request, it adds an `Origin` header:

```
GET /api/users HTTP/1.1
Origin: http://localhost:5173
```

The server responds with an `Access-Control-Allow-Origin` header:

```
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://localhost:5173
```

If the origin matches, the browser allows the response through. If not, it blocks it.

For "complex" requests (POST with JSON, PUT, DELETE), the browser first sends a **preflight request** — an OPTIONS request to check if the actual request is allowed:

```
1. Browser sends OPTIONS /api/users (preflight)
2. Server responds with allowed methods/headers
3. Browser sends actual POST /api/users
4. Server responds with data
```

The CORS middleware handles all of this automatically. You don't need to think about preflight requests.

## Debugging CORS errors

If you still see CORS errors after adding the middleware:

<Steps>
  <Step title="Check the origin matches exactly">
    `http://localhost:5173` is not the same as `http://localhost:5173/` (trailing slash) or `http://127.0.0.1:5173` (IP vs hostname).
  </Step>

  <Step title="Make sure middleware is added before routes">
    The CORS middleware must be added before your route definitions. FastAPI processes middleware in order.
  </Step>

  <Step title="Check the Network tab">
    Open DevTools → Network tab. Look at the failing request. Check the Response Headers for `Access-Control-Allow-Origin`. If it's missing, the middleware isn't configured correctly.
  </Step>

  <Step title="Restart your backend">
    Environment variable changes require restarting the server. `uvicorn --reload` only watches for file changes, not `.env` changes.
  </Step>
</Steps>

<Tip>
  CORS errors always appear in the browser console, never in the backend terminal. If your backend terminal shows no errors but the browser does, it's almost certainly CORS.
</Tip>

## What's next?

Your frontend can talk to your backend. But right now, `fetch()` calls are scattered throughout your components. Let's organize them into a dedicated API client layer.

<Card title="API client layer" icon="layer-group" href="/full-stack/api-client-layer">
  Separate API calls from components for cleaner, more maintainable code
</Card>


# Update operation
Source: https://js.maxbraglia.com/full-stack/update-operation

Edit existing records with a form that sends PUT requests to your API

## Two steps: load, then save

Updating a record means: load the current data into a form, let the user edit it, then send the changes back to the API.

<Info>
  The companion repo keeps update simpler and reuses `UserCreate` for `PUT /api/users/{id}` (full replacement). This lesson introduces a separate `UserUpdate` model with optional fields to teach the common "partial update shape" pattern.
</Info>

<Tabs>
  <Tab title="Backend (Python)">
    ```python theme={null}
    class UserUpdate(BaseModel):
        name: str | None = None
        email: str | None = None

    @app.put("/api/users/{user_id}")
    def update_user(user_id: int, updates: UserUpdate):
        user = find_user(user_id)
        if not user:
            raise HTTPException(status_code=404, detail="User not found")

        if updates.name is not None:
            user["name"] = updates.name
        if updates.email is not None:
            user["email"] = updates.email

        return user
    ```
  </Tab>

  <Tab title="API Client (JS)">
    ```jsx theme={null}
    export async function updateUser(id, data) {
      const response = await fetch(`${API_URL}/api/users/${id}`, {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
      });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return response.json();
    }
    ```
  </Tab>
</Tabs>

## The edit form component

The key difference from the Create form: initialize state with the existing data.

```jsx theme={null}
import { useState } from 'react';
import { updateUser } from '../api/users';

function EditUserForm({ user, onSave, onCancel }) {
  const [formData, setFormData] = useState({
    name: user.name,
    email: user.email,
  });
  const [error, setError] = useState(null);
  const [saving, setSaving] = useState(false);

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
  }

  async function handleSubmit(e) {
    e.preventDefault();
    setError(null);
    setSaving(true);

    try {
      const updatedUser = await updateUser(user.id, formData);
      onSave(updatedUser); // Tell parent about the update
    } catch (err) {
      setError(err.message);
    } finally {
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={formData.name} onChange={handleChange} />
      <input name="email" value={formData.email} onChange={handleChange} />

      {error && <p className="error">{error}</p>}

      <button type="submit" disabled={saving}>
        {saving ? "Saving..." : "Save Changes"}
      </button>
      <button type="button" onClick={onCancel}>
        Cancel
      </button>
    </form>
  );
}
```

Notice:

* **State initialized from `user` prop** — form starts with current values
* **`onSave` callback** — parent receives the updated object from the API
* **`onCancel` callback** — lets the user exit edit mode without saving
* **Cancel is `type="button"`** — prevents it from submitting the form

## Toggle between view and edit mode

The parent component switches between displaying data and showing the edit form:

```jsx theme={null}
function UserCard({ user, onUpdate }) {
  const [editing, setEditing] = useState(false);

  function handleSave(updatedUser) {
    onUpdate(updatedUser);
    setEditing(false);
  }

  if (editing) {
    return (
      <EditUserForm
        user={user}
        onSave={handleSave}
        onCancel={() => setEditing(false)}
      />
    );
  }

  return (
    <div className="user-card">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
      <button onClick={() => setEditing(true)}>Edit</button>
    </div>
  );
}
```

```jsx theme={null}
function UserDashboard() {
  const [users, setUsers] = useState([]);

  function handleUpdate(updatedUser) {
    setUsers(prev =>
      prev.map(u => u.id === updatedUser.id ? updatedUser : u)
    );
  }

  return (
    <div>
      {users.map(user => (
        <UserCard
          key={user.id}
          user={user}
          onUpdate={handleUpdate}
        />
      ))}
    </div>
  );
}
```

The state update uses `.map()` — replace the old user with the updated one, leave everything else unchanged.

<Info>
  `prev.map(u => u.id === updatedUser.id ? updatedUser : u)` is the standard pattern for updating one item in a list. It creates a new array where only the matching item is replaced. You'll use this pattern constantly.
</Info>

## Optimistic vs pessimistic updates

**Pessimistic** (wait for server, then update UI):

```jsx theme={null}
async function handleSave(formData) {
  setSaving(true);
  try {
    const updated = await updateUser(user.id, formData); // Wait for API
    onUpdate(updated); // Then update UI
  } catch (err) {
    setError(err.message); // Show error, UI unchanged
  } finally {
    setSaving(false);
  }
}
```

**Optimistic** (update UI immediately, roll back on error):

```jsx theme={null}
async function handleSave(formData) {
  const previousUser = { ...user }; // Save backup

  // Update UI immediately (optimistic)
  onUpdate({ ...user, ...formData });
  setEditing(false);

  try {
    await updateUser(user.id, formData); // Confirm with server
  } catch (err) {
    onUpdate(previousUser); // Roll back on failure
    setError("Save failed. Your changes were reverted.");
    setEditing(true);
  }
}
```

| Approach    | UX                     | Complexity   | When to use                       |
| ----------- | ---------------------- | ------------ | --------------------------------- |
| Pessimistic | Spinner, then update   | Simple       | Most operations (start here)      |
| Optimistic  | Instant, may roll back | More complex | Frequent actions (likes, toggles) |

<Tip>
  Start with pessimistic updates. They're simpler and always correct. Only switch to optimistic updates for actions where the slight delay feels sluggish — like toggling a checkbox or liking a post.
</Tip>

## What's next?

You can create, read, and update. The last CRUD operation: deleting records with confirmation.

<Card title="Delete operation" icon="trash" href="/full-stack/delete-operation">
  Remove records with confirmation and proper error handling
</Card>


# Your first JavaScript file
Source: https://js.maxbraglia.com/getting-started/first-javascript-file

Create and run your first JavaScript program

## Creating hello.js

<Steps>
  <Step title="Create a project folder">
    Open your terminal and create a folder for your practice files:

    ```bash theme={null}
    mkdir js-practice
    cd js-practice
    ```
  </Step>

  <Step title="Create the file">
    Open this folder in VS Code:

    ```bash theme={null}
    code .
    ```

    Create a new file called `hello.js` and add this code:

    ```javascript hello.js theme={null}
    const name = "Sarah";
    const language = "JavaScript";

    console.log(`Hello, ${name}!`);
    console.log(`Welcome to ${language} for Web Dev.`);
    console.log("Let's build something.");
    ```
  </Step>

  <Step title="Run it">
    Open the integrated terminal in VS Code (`` Ctrl+` ``) and run:

    ```bash theme={null}
    node hello.js
    ```

    ```
    Hello, Sarah!
    Welcome to JavaScript for Web Dev.
    Let's build something.
    ```
  </Step>
</Steps>

That's it. You just wrote and ran a JavaScript program.

## What's happening here

```javascript theme={null}
const name = "Sarah";              // Create a variable
console.log(`Hello, ${name}!`);    // Print to the terminal
```

* `const` declares a variable (you'll learn more in the JavaScript Core section)
* `console.log()` prints output to the terminal — JavaScript's version of Python's `print()`
* Backticks `` ` `` with `${}` let you embed variables in strings — like Python's f-strings

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const name = "Sarah";
    console.log(`Hello, ${name}!`);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    name = "Sarah"
    print(f"Hello, {name}!")
    ```
  </Tab>
</Tabs>

## Try the browser console

You can also run JavaScript directly in your browser. Open any browser, press `F12`, and click the **Console** tab.

```javascript theme={null}
// Type this directly in the browser console:
console.log("This runs in the browser!");
2 + 2
// 4
```

The browser console evaluates expressions immediately and shows the result. You don't need `console.log()` for simple expressions — the console shows the return value automatically.

<Tip>
  Use the browser console for quick experiments. Use `.js` files with Node.js for anything you want to save.
</Tip>

## What's next?

You've run JavaScript in two places — Node.js and the browser console. Let's explore the different ways to run JavaScript during development.

<Card title="Running JavaScript" icon="terminal" href="/getting-started/running-javascript">
  All the ways to run JavaScript code
</Card>


# Installing Node.js
Source: https://js.maxbraglia.com/getting-started/installing-node

Set up Node.js on your machine so you can run JavaScript outside the browser

## What is Node.js?

Node.js lets you run JavaScript outside of a web browser. Without it, JavaScript can only run inside a browser tab. With it, you can run JavaScript files from your terminal, use build tools, and install packages.

You need Node.js for two things in this course:

1. Running JavaScript files during the learning sections
2. Running React's development server when you build UIs

<Info>
  Node.js also comes with **npm** (Node Package Manager), which you'll use to install libraries like React. You get both when you install Node.js.
</Info>

## Installation

<Tabs>
  <Tab title="macOS">
    The easiest way is with Homebrew:

    ```bash theme={null}
    brew install node
    ```

    If you don't have Homebrew, install it first from [brew.sh](https://brew.sh), or download the installer directly from [nodejs.org](https://nodejs.org).
  </Tab>

  <Tab title="Windows">
    Download the LTS installer from [nodejs.org](https://nodejs.org) and run it. Accept all the default options.

    Alternatively, if you use Chocolatey:

    ```powershell theme={null}
    choco install nodejs-lts
    ```
  </Tab>

  <Tab title="Linux">
    Using your package manager:

    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt update
    sudo apt install nodejs npm

    # Fedora
    sudo dnf install nodejs
    ```

    For the latest version, use [NodeSource](https://github.com/nodesource/distributions):

    ```bash theme={null}
    curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
    sudo apt install -y nodejs
    ```
  </Tab>
</Tabs>

<Tip>
  Always install the **LTS** (Long Term Support) version. It's the stable release that won't surprise you with breaking changes.
</Tip>

## Verifying installation

Open your terminal and run these two commands:

```bash theme={null}
node -v
# v20.11.0 (or similar)

npm -v
# 10.2.4 (or similar)
```

If both commands print a version number, you're good to go. The exact version numbers don't matter as long as Node.js is version 18 or higher.

<Warning>
  If you get "command not found," your terminal might not see the installation yet. Try closing and reopening your terminal. On Windows, you may need to restart your computer.
</Warning>

## Quick test

Let's make sure Node.js actually works. Type this directly in your terminal:

```bash theme={null}
node -e 'console.log("Node.js is working!")'
# Node.js is working!
```

The `-e` flag lets you run a one-line JavaScript command without creating a file. You'll create proper files in the next lessons.

## What's next?

Node.js is installed. Now let's set up VS Code with the right extensions for JavaScript development.

<Card title="Setting up VS Code" icon="code" href="/getting-started/vscode-setup">
  Configure your editor for JavaScript
</Card>


# Project setup
Source: https://js.maxbraglia.com/getting-started/project-setup

Initialize a JavaScript project with npm and configure the basics

## Creating a project

Let's set up a proper JavaScript project from scratch. This is the same process you'll follow for every new project.

<Steps>
  <Step title="Create a folder and initialize npm">
    ```bash theme={null}
    mkdir my-js-project
    cd my-js-project
    npm init -y
    ```

    The `-y` flag accepts all defaults. This creates a `package.json` file in your folder.
  </Step>

  <Step title="Create your entry file">
    Create an `index.js` file:

    ```javascript index.js theme={null}
    const APP_NAME = "My JS Project";

    console.log(`${APP_NAME} is running!`);
    ```
  </Step>

  <Step title="Add a start script">
    Open `package.json` and update the `scripts` section:

    ```json package.json theme={null}
    {
      "name": "my-js-project",
      "version": "1.0.0",
      "scripts": {
        "start": "node index.js"
      }
    }
    ```

    Now you can run your project with:

    ```bash theme={null}
    npm start
    # My JS Project is running!
    ```
  </Step>
</Steps>

## Project structure

A typical JavaScript project looks like this:

```
my-js-project/
├── node_modules/     # Installed packages (don't touch)
├── src/              # Your source code
│   └── index.js
├── package.json      # Project config and dependencies
├── package-lock.json # Locked dependency versions
├── .gitignore        # Files to exclude from git
└── README.md
```

For the practice exercises in this course, you don't need the `src/` folder — a flat structure with `.js` files at the root is fine. You'll use a more structured layout when you get to React.

## Setting up .gitignore

Create a `.gitignore` file in your project root:

```text .gitignore theme={null}
# Dependencies
node_modules/

# Environment variables
.env
.env.local

# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/
*.swp
```

The most important line is `node_modules/`. This folder can contain thousands of files and hundreds of megabytes. Everyone who clones your project runs `npm install` to generate their own copy.

<Warning>
  Always add `.env` to `.gitignore`. Environment files often contain API keys, database passwords, and other secrets that should never be committed to git.
</Warning>

## .env files

You'll use `.env` files later in the course to store configuration like API URLs. Here's a preview:

```text .env theme={null}
VITE_API_URL=http://localhost:8000
DATABASE_URL=postgresql://localhost:5432/myapp
```

For now, just know that:

1. `.env` files store configuration as key-value pairs
2. They should never be committed to git
3. Create a `.env.example` file (without real values) to show other developers what variables they need

<Tip>
  Create a `.env.example` file with placeholder values so other developers know what environment variables your project expects. Commit this file to git.
</Tip>

## Verify your setup

At this point, you should have:

* [x] Node.js installed (`node -v` shows a version)
* [x] npm available (`npm -v` shows a version)
* [x] VS Code with ESLint and Prettier extensions
* [x] A practice folder where you can create and run `.js` files

If all of that checks out, you're ready to learn JavaScript.

## What's next?

Your development environment is set up. Time to learn the language. Let's start with how JavaScript works and how it compares to Python.

<Card title="JavaScript basics" icon="rocket" href="/javascript-core/overview">
  What JavaScript is, how it compares to Python, and essential syntax
</Card>


# Running JavaScript
Source: https://js.maxbraglia.com/getting-started/running-javascript

Different ways to run JavaScript code during development

## Three ways to run JavaScript

You'll use three environments during this course. Each one is useful for different things.

## Node.js in the terminal

Run any `.js` file from your terminal:

```bash theme={null}
node myfile.js
```

This is what you'll use for most of the learning sections (JavaScript Core, Working with Data, Async & APIs). It's the closest thing to running `python myfile.py`.

```javascript practice.js theme={null}
const prices = [29.99, 49.99, 9.99, 79.99];
const total = prices.reduce((sum, price) => sum + price, 0);
console.log(`Total: $${total.toFixed(2)}`); // "Total: $169.96"
```

```bash theme={null}
node practice.js
# Total: $169.96
```

<Tip>
  Create a `practice.js` file in your `js-practice` folder. Use it as a scratch pad — edit it, run it, edit it again. You don't need a new file for every experiment.
</Tip>

## Browser console

Open any browser, press `F12`, and use the Console tab for quick experiments.

```javascript theme={null}
// Good for: testing one-liners, checking syntax, quick math
"hello".toUpperCase()  // "HELLO"
[1, 2, 3].includes(2)  // true
typeof null  // "object" (yes, really)
```

The browser console is interactive — it evaluates each line and shows the result. No `console.log()` needed for simple expressions.

<Warning>
  The browser console has access to web APIs (like `document` and `window`) that Node.js doesn't have. If you're testing pure JavaScript logic, either environment works. If you're testing DOM or browser features, use the browser console.
</Warning>

## VS Code integrated terminal

The integrated terminal in VS Code (`` Ctrl+` ``) runs Node.js commands without leaving your editor. This is where you'll spend most of your time:

1. Write code in the editor panel
2. Switch to the terminal (`` Ctrl+` ``)
3. Run `node filename.js`
4. See the output
5. Edit and repeat

```bash theme={null}
# Your typical workflow:
node hello.js
# (see output, make changes, run again)
node hello.js
```

<Info>
  Later in the course, when you work with React, you'll run `npm run dev` in this terminal to start a development server. The server watches for file changes and refreshes your browser automatically.
</Info>

## Which one should I use?

| Environment                  | Best for                                                |
| ---------------------------- | ------------------------------------------------------- |
| **Node.js** (`node file.js`) | Writing and running JavaScript files, course exercises  |
| **Browser console** (`F12`)  | Quick experiments, testing one-liners, DOM/browser APIs |
| **VS Code terminal**         | Everything — it runs Node.js from within your editor    |

For this course, you'll mostly use VS Code's integrated terminal to run Node.js. The browser console is there for quick checks.

## What's next?

You can write and run JavaScript. Before we dive into the language itself, let's understand npm — the tool that manages JavaScript packages and dependencies.

<Card title="Understanding npm" icon="cube" href="/getting-started/understanding-npm">
  How JavaScript manages packages and dependencies
</Card>


# Understanding npm
Source: https://js.maxbraglia.com/getting-started/understanding-npm

Learn how npm manages packages and dependencies for JavaScript projects

## What is npm?

npm (Node Package Manager) is JavaScript's package manager. It installs libraries, manages dependencies, and runs project scripts. It came bundled with Node.js when you installed it.

If you've used `pip` in Python, npm is the same idea:

| Python                 | JavaScript          |
| ---------------------- | ------------------- |
| `pip install requests` | `npm install axios` |
| `requirements.txt`     | `package.json`      |
| `pip freeze`           | `npm list`          |
| `venv/`                | `node_modules/`     |

## package.json

Every JavaScript project has a `package.json` file. It describes your project and lists its dependencies — like a `requirements.txt` with extra features.

```json package.json theme={null}
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A practice JavaScript project",
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js"
  },
  "dependencies": {
    "axios": "^1.6.0"
  },
  "devDependencies": {
    "prettier": "^3.1.0"
  }
}
```

The key sections:

* **name** and **version** — project identity
* **scripts** — commands you can run with `npm run <name>`
* **dependencies** — packages your app needs to run
* **devDependencies** — packages you only need during development (linters, formatters, test tools)

## Installing packages

```bash theme={null}
# Install a package and add to dependencies
npm install axios

# Install a package as a dev dependency
npm install --save-dev prettier

# Install all dependencies listed in package.json
npm install
```

When you run `npm install`, two things happen:

1. The package code downloads into a `node_modules/` folder
2. The package name and version are added to `package.json`

<Warning>
  Never commit `node_modules/` to git. It can contain hundreds of megabytes of files. Add it to `.gitignore` and let each developer run `npm install` to download their own copy.
</Warning>

## Running scripts

The `scripts` section in `package.json` lets you define shortcut commands:

```json theme={null}
{
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "format": "prettier --write ."
  }
}
```

```bash theme={null}
# Run a script
npm run dev
npm run format

# "start" and "test" are special — no "run" needed
npm start
npm test
```

<Tip>
  When you see instructions like "run `npm run dev`" in a project's README, they're referring to a script defined in `package.json`. Check the `scripts` section to see what command it actually runs.
</Tip>

## package-lock.json

When you install packages, npm also creates a `package-lock.json` file. This locks the exact versions of every package and sub-dependency so that everyone on your team gets identical installs.

* **Do** commit `package-lock.json` to git
* **Don't** edit it manually — npm manages it for you

<Info>
  `package-lock.json` is like a more detailed version of `pip freeze > requirements.txt`. It ensures reproducible installs across different machines.
</Info>

## What's next?

You know how npm works. Let's put it all together and set up a proper JavaScript project from scratch.

<Card title="Project setup" icon="folder" href="/getting-started/project-setup">
  Initialize a JavaScript project and configure the basics
</Card>


# Setting up VS Code
Source: https://js.maxbraglia.com/getting-started/vscode-setup

Configure VS Code with the essential extensions for JavaScript development

## Why VS Code?

VS Code is the most popular editor for JavaScript development. It has built-in JavaScript support, a huge extension ecosystem, and an integrated terminal where you'll run your code.

If you're already using VS Code for Python, you just need a few extra extensions.

## Essential extensions

Install these two extensions from the VS Code Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`):

<Steps>
  <Step title="ESLint">
    Catches JavaScript errors and enforces code style as you type. It underlines problems in red and yellow so you can fix them before running your code.

    Search for: **ESLint** by Microsoft
  </Step>

  <Step title="Prettier">
    Automatically formats your code on save — consistent indentation, quotes, semicolons, line breaks. No more arguing about code style.

    Search for: **Prettier - Code formatter** by Prettier
  </Step>
</Steps>

<Tip>
  You probably already have the **Python** extension installed. Keep it — it won't conflict with JavaScript extensions. VS Code handles multiple languages fine.
</Tip>

## Keyboard shortcuts worth knowing

You don't need to memorize these now. Come back to this list when you're writing more code.

| Shortcut (Mac / Windows)         | What it does                           |
| -------------------------------- | -------------------------------------- |
| `Cmd+P` / `Ctrl+P`               | Quick open file by name                |
| `Cmd+Shift+P` / `Ctrl+Shift+P`   | Command Palette                        |
| `Cmd+D` / `Ctrl+D`               | Select next occurrence of current word |
| `Option+Up/Down` / `Alt+Up/Down` | Move line up or down                   |
| `Cmd+/` / `Ctrl+/`               | Toggle line comment                    |
| `` Ctrl+` ``                     | Toggle integrated terminal             |
| `Cmd+B` / `Ctrl+B`               | Toggle sidebar                         |

<Tip>
  The integrated terminal (`` Ctrl+` ``) is where you'll run `node` commands and start React development servers. Get comfortable switching between your code and the terminal.
</Tip>

## What's next?

Your editor is ready. Let's create your first JavaScript file and run it.

<Card title="Your first JavaScript file" icon="file-code" href="/getting-started/first-javascript-file">
  Create and run your first JavaScript program
</Card>


# How to follow this course
Source: https://js.maxbraglia.com/introduction/how-to-follow

Tips for getting the most out of each lesson

## Two ways to run JavaScript

Throughout this course, you'll run JavaScript in two places:

### Browser console (for quick experiments)

Open any browser, press `F12` (or `Cmd+Option+J` on Mac), and click the **Console** tab. Type JavaScript directly and press Enter.

```javascript theme={null}
// Try this right now in your browser console:
const greeting = "Hello from the console!";
console.log(greeting); // "Hello from the console!"
```

The browser console is perfect for testing one-liners, checking syntax, and experimenting with small ideas.

### VS Code + Node.js (for everything else)

For anything more than a quick test, you'll write code in VS Code and run it with Node.js. You'll set this up in the next section.

```javascript hello.js theme={null}
const name = "Sarah";
console.log(`Welcome to JavaScript, ${name}!`);
```

```bash theme={null}
node hello.js
# Welcome to JavaScript, Sarah!
```

<Tip>
  Use the browser console to quickly verify how something works. Use VS Code + Node.js for writing actual code you want to keep.
</Tip>

## Where code runs in this course

Different sections run code in different places. This is normal:

| Where                        | Use it for                                                    |
| ---------------------------- | ------------------------------------------------------------- |
| **Browser Console**          | Quick JavaScript experiments and syntax checks                |
| **Node.js (`node file.js`)** | JavaScript fundamentals practice                              |
| **Browser + HTML page**      | DOM and browser API lessons                                   |
| **React + Vite**             | Components, JSX, state, effects, and full-stack frontend work |

## Code along with every example

Every lesson leads with working code. You'll get the most out of this course by typing each example yourself — not copying and pasting.

Why typing matters:

* You catch syntax differences between Python and JavaScript faster
* Your hands learn the patterns (semicolons, curly braces, `const`)
* You'll notice things you'd skip when just reading

<Warning>
  Copying and pasting code is the fastest way to learn nothing. Even if it feels slow at first, type it out. After a few lessons, the JavaScript syntax will feel natural.
</Warning>

## Recommended study loop (use this every lesson)

1. **Read the example once** — don't try to memorize it
2. **Type it yourself** — don't paste
3. **Run it** — confirm it works
4. **Break one thing on purpose** — change something small and observe the result
5. **Explain it in one sentence** — what problem does this concept solve?

## How each lesson is structured

Every lesson follows the same pattern:

1. **What and why** — 2-3 sentences explaining the concept
2. **Code examples** — working code you can run immediately
3. **Explanation** — brief explanation after the code, not before
4. **Tips and warnings** — best practices and common gotchas
5. **Common mistakes** — things that trip people up, with fixes
6. **What's next** — link to the next lesson

Code examples show output as inline comments:

```javascript theme={null}
const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2);
console.log(doubled); // [2, 4, 6, 8, 10]
```

## Learning tips

**Don't memorize syntax.** You'll look things up constantly — every developer does. Focus on understanding *what* each concept does and *when* to use it. The syntax will stick through repetition.

**Break things on purpose.** When a code example works, change something and see what breaks. Remove a semicolon. Forget an `await`. Use `=` instead of `===`. The error messages teach you more than the working code.

**Skip what you already know.** If you already understand variables and data types from another language, skim those lessons and jump to what's new. The sections are designed to build on each other, but you don't need to read every word.

**Use the companion repo.** The [FastAPI + React repository](https://github.com/jmedia65/fastapi-react-full-stack) is a real, working application. Before Section 8, just browse the structure. In Section 8, use it deeply: trace one request from React → API client → FastAPI route → response.

## How to know you're ready to move on

You don't need perfection. Move on when you can say:

* I can run the example without guessing
* I can change one part and predict the result
* I can explain what problem this concept solves
* I know when I'd use it in a FastAPI + frontend workflow

## What's next?

Time to set up your development environment. Let's install Node.js.

<Card title="Installing Node.js" icon="download" href="/getting-started/installing-node">
  Get JavaScript running on your machine
</Card>


# Is this for you?
Source: https://js.maxbraglia.com/introduction/is-this-for-you

Find out if this course matches your background and goals

## Prerequisites

You should know how to write basic Python — variables, functions, loops, dictionaries. You don't need to be an expert. If you've built a simple FastAPI app or followed a Python tutorial, you have enough knowledge to follow along.

```python theme={null}
# If you can read and understand this, you're ready:
def get_user(user_id):
    users = {"1": "Sarah", "2": "John", "3": "Alice"}
    return users.get(user_id, "Unknown")

for id in ["1", "2", "3"]:
    print(get_user(id))
```

You don't need any prior JavaScript experience. That's what this course is for.

<Info>
  What feels hard at first (and that's normal): destructuring syntax, closures, async/await + fetch errors, JSX, and `useEffect` dependency arrays. These are exactly the concepts this course is designed to make click.
</Info>

## This course is for you if...

* You know Python and want to build web application frontends
* You're building (or plan to build) full-stack apps with FastAPI + React
* You want a practical, focused path through JavaScript — not a 40-hour deep dive
* You learn best by seeing working code first, then understanding why it works

## This course is NOT for you if...

* You've never programmed before — start with a Python fundamentals course first
* You want deep JavaScript internals (prototype chains, event loop mechanics, the `this` keyword)
* You're looking for advanced React patterns (Context, Reducers, custom hooks)
* You want to learn Vue, Angular, or Svelte — this course is React-focused

<Info>
  Advanced topics like TypeScript, React Router, and state management libraries are mentioned in the [Next Steps](/next-steps/recommended-resources) section as paths to explore after this course.
</Info>

## What you'll be able to do after

By the end of this course, you'll confidently:

1. Read and write modern JavaScript (ES6+)
2. Build interactive UIs with React components
3. Fetch data from a FastAPI backend and display it
4. Handle forms, loading states, and errors
5. Structure a full-stack project with clean separation between frontend and backend

## Time commitment

Each lesson takes 5-15 minutes to read and practice. The full course has about 70 lessons across 9 sections.

* **Quick pass**: \~10-15 hours if you read and follow along
* **Deep practice**: \~20-25 hours if you type every example and experiment

<Tip>
  Don't rush. The most effective approach is to type the code examples yourself (don't copy-paste) and experiment with small changes to see what happens.
</Tip>

## What's next?

Ready to get started? Let's talk about how to follow the course effectively.

<Card title="How to follow this course" icon="book" href="/introduction/how-to-follow">
  Tips for getting the most out of each lesson
</Card>


# Welcome to JavaScript for Web Dev
Source: https://js.maxbraglia.com/introduction/welcome

What you'll build, what you'll learn, and how this course is structured

## What you'll build

By the end of this course, you'll build interactive web UIs with React and connect them to a FastAPI backend. You'll go from "I know Python" to "I can build a full-stack web app."

```javascript theme={null}
// This is the kind of code you'll write confidently:
async function getUsers() {
  const response = await fetch("http://localhost:8000/api/users");
  const data = await response.json();
  return data;
}
```

```jsx UserList.jsx theme={null}
import { useState, useEffect } from 'react';

function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    getUsers().then(data => setUsers(data));
  }, []);

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

That might look unfamiliar now. By Section 8, you'll write code like this without thinking twice.

## What you'll learn

This course covers the JavaScript you actually need for web development — not everything JavaScript can do, but the 20% you'll use 80% of the time.

* **JavaScript fundamentals** — variables, functions, arrays, objects, and how they differ from Python
* **Async programming** — fetch data from APIs, handle errors, manage loading states
* **DOM basics** — select elements, handle events, work with forms
* **React** — components, props, state, effects, and common UI patterns
* **Full-stack integration** — connect a React frontend to a FastAPI backend with a complete CRUD app

<Info>
  This course has a companion repository: a production-ready FastAPI + React application you'll reference throughout Section 8. You can find it on [GitHub](https://github.com/jmedia65/fastapi-react-full-stack).
</Info>

## Course structure

The course is organized into 9 sections. Each one builds on the last:

| Section               | What you'll learn                                                   |
| --------------------- | ------------------------------------------------------------------- |
| **Introduction**      | What you'll build, who the course is for, and how to study it       |
| **Getting Started**   | Install Node.js, set up VS Code, run your first JavaScript file     |
| **JavaScript Core**   | Variables, data types, functions, scope — the foundation            |
| **Working with Data** | Arrays, objects, destructuring, JSON — how data moves around        |
| **Async & APIs**      | Promises, async/await, fetch — how to talk to your backend          |
| **DOM & Browser**     | Select elements, handle events, work with forms — the browser layer |
| **React Essentials**  | Components, props, state, effects — building interactive UIs        |
| **Full-Stack**        | Connect React to FastAPI — build a real CRUD application            |
| **Next Steps**        | Where to go after this course                                       |

<Info>
  How the sections depend on each other:

  * **JavaScript Core + Working with Data** → the syntax and patterns React code is built on
  * **Async & APIs** → required before React data fetching feels natural
  * **DOM & Browser** → helps you understand what React is abstracting
  * **React Essentials** → prerequisite for the Full-Stack section
  * **Full-Stack** → combines everything into one app flow (frontend + FastAPI)
</Info>

<Tip>
  You don't have to go in order, but the sections are designed to build on each other. If you already know some JavaScript, feel free to skip ahead to what's new for you.
</Tip>

## What's next?

Before diving in, let's make sure this course is the right fit for your background and goals.

<Card title="Is this for you?" icon="user" href="/introduction/is-this-for-you">
  Check if your background matches what this course expects
</Card>


# Arrow functions
Source: https://js.maxbraglia.com/javascript-core/arrow-functions

Write shorter, cleaner functions with the modern arrow syntax

## The arrow function syntax

Arrow functions are a shorter way to write functions. They were added in ES6 and are now the most common function syntax in modern JavaScript — especially in React.

```javascript theme={null}
// Regular function
function add(a, b) {
  return a + b;
}

// Arrow function
const add = (a, b) => {
  return a + b;
};

console.log(add(3, 5)); // 8
```

Drop the `function` keyword, add `=>` after the parameters. That's it.

## Implicit return

When your function body is a single expression, you can skip the curly braces and the `return` keyword:

```javascript theme={null}
// Full syntax
const double = (n) => {
  return n * 2;
};

// Implicit return — same thing, shorter
const double = (n) => n * 2;

console.log(double(5)); // 10
```

This works because JavaScript automatically returns the expression after `=>` when there are no curly braces.

```javascript theme={null}
// More examples of implicit return
const greet = (name) => `Hello, ${name}!`;
const isAdult = (age) => age >= 18;
const getFullName = (first, last) => `${first} ${last}`;

console.log(greet("Sarah"));            // "Hello, Sarah!"
console.log(isAdult(25));               // true
console.log(getFullName("Sarah", "Chen")); // "Sarah Chen"
```

<Tip>
  If your function does one thing and returns a value, use the implicit return. If it has multiple lines or side effects (like `console.log`), use curly braces with an explicit `return`.
</Tip>

## Single parameter shorthand

When an arrow function has exactly one parameter, you can drop the parentheses:

```javascript theme={null}
// With parentheses
const double = (n) => n * 2;

// Without parentheses — same thing
const double = n => n * 2;

// Zero parameters — parentheses required
const getTimestamp = () => Date.now();

// Multiple parameters — parentheses required
const add = (a, b) => a + b;
```

<Info>
  Some teams require parentheses around all parameters for consistency. Either style is fine — Prettier will handle this for you based on your config.
</Info>

## Where you'll use arrow functions

Arrow functions shine as callbacks — functions you pass to other functions. You'll write these constantly:

```javascript theme={null}
// Array methods
const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2);        // [2, 4, 6, 8, 10]
const evens = numbers.filter(n => n % 2 === 0); // [2, 4]

// Sorting
const names = ["Charlie", "Alice", "Bob"];
names.sort((a, b) => a.localeCompare(b)); // ["Alice", "Bob", "Charlie"]

// Timers
setTimeout(() => {
  console.log("This runs after 1 second");
}, 1000);
```

In React, arrow functions are everywhere:

```jsx theme={null}
// Event handlers
<button onClick={() => setCount(count + 1)}>Increment</button>

// Rendering lists
{users.map(user => <li key={user.id}>{user.name}</li>)}

// Effects
useEffect(() => {
  fetchUsers();
}, []);
```

## Arrow functions vs regular functions

For this course, here's the practical rule:

| Use case                       | Syntax                     |
| ------------------------------ | -------------------------- |
| Standalone, named functions    | `function greet(name) { }` |
| Callbacks and inline functions | `(params) => expression`   |
| React event handlers           | `() => doSomething()`      |
| Array methods (.map, .filter)  | `item => transform(item)`  |

<Info>
  Arrow functions have a technical difference with `this` binding, but you won't encounter it in this course. React function components and hooks don't rely on `this`, so it's a non-issue. If you're curious, MDN has a [detailed explanation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions).
</Info>

## Comparing to Python lambdas

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Arrow functions can have multiple lines
    const calculateTotal = (price, taxRate) => {
      const tax = price * taxRate;
      return price + tax;
    };

    // Or a single expression
    const double = n => n * 2;

    // Used as callbacks
    const prices = [10, 20, 30];
    const withTax = prices.map(p => p * 1.08);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Lambdas are limited to one expression
    double = lambda n: n * 2

    # For anything more, you need def
    def calculate_total(price, tax_rate):
        tax = price * tax_rate
        return price + tax

    # Used as callbacks
    prices = [10, 20, 30]
    with_tax = list(map(lambda p: p * 1.08, prices))
    ```
  </Tab>
</Tabs>

JavaScript's arrow functions are more versatile than Python's lambdas. They can have multiple lines, multiple statements, and they're used far more often because JavaScript relies heavily on callbacks.

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting to return with curly braces">
    ```javascript theme={null}
    // ❌ Wrong: Curly braces but no return
    const double = (n) => {
      n * 2; // This computes but doesn't return anything
    };
    console.log(double(5)); // undefined

    // ✅ Correct: Either add return...
    const double = (n) => {
      return n * 2;
    };

    // ✅ ...or use implicit return (no curly braces)
    const double = (n) => n * 2;
    ```

    <Warning>
      With curly braces, you must use `return`. Without curly braces, the return is implicit. Mixing these up is the most common arrow function mistake.
    </Warning>
  </Accordion>

  <Accordion title="Returning an object literal">
    ```javascript theme={null}
    // ❌ Wrong: JavaScript thinks {} is a function body
    const getUser = () => { name: "Sarah", age: 28 }; // SyntaxError

    // ✅ Correct: Wrap the object in parentheses
    const getUser = () => ({ name: "Sarah", age: 28 });
    console.log(getUser()); // { name: "Sarah", age: 28 }
    ```

    <Warning>
      When implicitly returning an object, wrap it in parentheses `()`. Without them, JavaScript interprets the curly braces as a function body, not an object.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can write functions in both styles. Now let's look at what goes *inside* the parentheses — parameters, default values, and destructuring.

<Card title="Parameters and arguments" icon="sliders" href="/javascript-core/parameters-arguments">
  Default values, rest parameters, and destructuring
</Card>


# Closures
Source: https://js.maxbraglia.com/javascript-core/closures

Understand how functions remember their surrounding variables

## What is a closure?

A closure is a function that remembers the variables from the scope where it was created — even after that scope has finished executing.

You've already been using closures without knowing it. If you've written a function inside another function and used a variable from the outer function, that's a closure.

```javascript theme={null}
function createGreeter(greeting) {
  // This inner function "closes over" the greeting variable
  return function(name) {
    return `${greeting}, ${name}!`;
  };
}

const sayHello = createGreeter("Hello");
const sayHey = createGreeter("Hey");

console.log(sayHello("Sarah")); // "Hello, Sarah!"
console.log(sayHey("John"));    // "Hey, John!"
```

`createGreeter` has finished running, but `sayHello` still remembers that `greeting` was `"Hello"`. That's a closure.

## Comparing to Python

Closures are not "a JavaScript thing" — Python has them too. If you've written a nested function that uses a variable from the outer function, you've already used closures.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    function makeGreeter(greeting) {
      return function(name) {
        return `${greeting}, ${name}!`;
      };
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def make_greeter(greeting):
        def greet(name):
            return f"{greeting}, {name}!"
        return greet
    ```
  </Tab>
</Tabs>

Same idea in both languages: the inner function keeps access to `greeting` after the outer function returns.

## Why closures matter

Closures aren't an abstract concept you need to master — they're a pattern that shows up naturally in JavaScript. Here are the places you'll actually use them.

### Callbacks with context

```javascript theme={null}
function setupLogger(prefix) {
  return function(message) {
    console.log(`[${prefix}] ${message}`);
  };
}

const apiLog = setupLogger("API");
const uiLog = setupLogger("UI");

apiLog("Fetching users");  // "[API] Fetching users"
uiLog("Button clicked");   // "[UI] Button clicked"
```

Each logger "remembers" its prefix. You create it once and use it everywhere.

### Event handlers in loops

```javascript theme={null}
function attachHandlers(buttons) {
  for (let i = 0; i < buttons.length; i++) {
    buttons[i].addEventListener("click", () => {
      console.log(`Button ${i} clicked`); // Each handler remembers its own "i"
    });
  }
}
```

Each click handler is a closure that captures its own copy of `i`. This is why `let` (block-scoped) works correctly in loops but `var` (function-scoped) doesn't.

<Info>
  Python mental model: this is the same family of problem as Python's "late binding" in loops (for example, lambdas in a loop all using the final value). In JavaScript, `let` usually gives you the behavior you wanted automatically.
</Info>

### Data privacy

```javascript theme={null}
function createCounter(initial = 0) {
  let count = initial; // Private — can't be accessed from outside

  return {
    increment: () => ++count,
    decrement: () => --count,
    getCount: () => count,
  };
}

const counter = createCounter(10);
console.log(counter.getCount());  // 10
counter.increment();
counter.increment();
console.log(counter.getCount());  // 12

// Can't access count directly
console.log(counter.count); // undefined
```

The `count` variable is completely private. The only way to interact with it is through the returned functions. This pattern is useful for creating modules and encapsulated state.

## Closures in React

You use closures in React without thinking about it. Every event handler inside a component is a closure:

```jsx theme={null}
function SearchBar() {
  const [query, setQuery] = useState("");

  const handleSubmit = () => {
    // This is a closure — it "closes over" the query variable
    console.log(`Searching for: ${query}`);
    fetch(`/api/search?q=${query}`);
  };

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button onClick={handleSubmit}>Search</button>
    </div>
  );
}
```

`handleSubmit` remembers `query` from the component scope. Every time the component re-renders, a new closure is created with the latest value of `query`.

<Info>
  This is why React state "works" — your event handlers are closures that capture the current state values. When you hear about "stale closures" in React, it means a function captured an old value of state. The `useEffect` dependency array exists to manage this.
</Info>

## Don't overthink it

Closures sound complicated when explained in theory, but they're a natural consequence of two things you already understand:

1. Functions can be defined inside other functions
2. Inner functions can access outer variables (lexical scope)

That's it. When the inner function outlives the outer function, it keeps access to those variables. That's a closure.

```javascript theme={null}
// You don't need to think "I'm creating a closure here"
// Just write the code naturally:

function fetchUserData(userId) {
  const url = `http://localhost:8000/api/users/${userId}`;

  // This callback is a closure — it uses "url" from the outer function
  return fetch(url)
    .then(response => response.json());
}
```

<Tip>
  Don't try to memorize closure rules. Write functions inside functions, use variables from the outer scope when it's natural, and you're using closures. The concept will solidify through practice.
</Tip>

<Tip>
  If you're a Python web dev, you've likely seen closures in decorator factories (functions that return decorators). JavaScript callbacks and React event handlers use the same underlying idea constantly.
</Tip>

## What's next?

You've covered the core of JavaScript — variables, types, strings, functions, scope, and closures. Now let's learn how to work with collections of data: arrays and objects.

<Card title="Arrays" icon="list" href="/working-with-data/arrays">
  Store and access collections of data
</Card>


# Comments
Source: https://js.maxbraglia.com/javascript-core/comments

Add notes and documentation to your JavaScript code

## Why comments?

Comments are notes in your code that JavaScript ignores. Use them to explain *why* something works a certain way — not *what* the code does (the code itself should be clear enough for that).

## Single-line comments

```javascript theme={null}
// This is a single-line comment
const API_URL = "http://localhost:8000"; // Inline comment after code

// Calculate total with tax
const subtotal = 99.99;
const tax = subtotal * 0.08;
const total = subtotal + tax;
```

Two slashes `//` start a single-line comment. Everything after `//` on that line is ignored.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Single-line comment
    const name = "Sarah"; // Inline comment
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Single-line comment
    name = "Sarah"  # Inline comment
    ```
  </Tab>
</Tabs>

Same idea, different character. `//` instead of `#`.

## Multi-line comments

```javascript theme={null}
/*
  This function fetches users from the API.
  It handles errors and returns an empty array
  if the request fails.
*/
async function getUsers() {
  // ...
}
```

Wrap longer comments in `/* */`. Use these for explaining complex logic or temporarily disabling blocks of code.

```javascript theme={null}
// Temporarily disable a block of code:
/*
const debugData = fetchDebugInfo();
console.log(debugData);
processDebugData(debugData);
*/
```

<Tip>
  In VS Code, select multiple lines and press `Cmd+/` (Mac) or `Ctrl+/` (Windows) to toggle comments on and off. This works for single-line comments — much faster than typing `//` on each line.
</Tip>

## JSDoc comments

JSDoc comments start with `/**` and describe functions, parameters, and return values. Your editor reads them and shows helpful tooltips.

```javascript theme={null}
/**
 * Calculate the total price with tax.
 * @param {number} subtotal - The price before tax
 * @param {number} taxRate - The tax rate as a decimal (e.g., 0.08 for 8%)
 * @returns {number} The total price including tax
 */
function calculateTotal(subtotal, taxRate) {
  return subtotal + (subtotal * taxRate);
}
```

When you hover over `calculateTotal` anywhere in your code, VS Code shows the description, parameter types, and return type. This is especially valuable when working on a team.

<Info>
  JSDoc comments are optional but helpful. You don't need to add them to every function — focus on public functions and anything with non-obvious parameters. When you later move to TypeScript, the type annotations handle much of what JSDoc does.
</Info>

## When to comment (and when not to)

```javascript theme={null}
// ❌ Bad: States the obvious
const age = 25; // Set age to 25

// ❌ Bad: Describes what the code does
// Loop through users and print names
for (const user of users) {
  console.log(user.name);
}

// ✅ Good: Explains WHY
// API returns dates as strings, need to convert for comparison
const createdAt = new Date(user.createdAt);

// ✅ Good: Warns about non-obvious behavior
// response.ok is false for 404/500 but fetch doesn't throw
if (!response.ok) {
  throw new Error(`HTTP error: ${response.status}`);
}
```

Good comments explain intent, warn about gotchas, or provide context that the code alone can't convey.

## What's next?

You've covered the fundamentals — variables, data types, strings, and comments. Now let's make your code reusable with functions.

<Card title="Functions basics" icon="code" href="/javascript-core/functions-basics">
  Write reusable blocks of code
</Card>


# Data types
Source: https://js.maxbraglia.com/javascript-core/data-types

Understand the different types of data JavaScript can work with

## Primitives

Every value in JavaScript has a type. There are seven primitive types, but you'll use five of them daily: strings, numbers, booleans, `null`, and `undefined`.

```javascript theme={null}
// String - text wrapped in quotes
const name = "Sarah Doe";
const email = 'sarah@example.com';
const greeting = `Hello, ${name}!`; // Template literal (more on this next lesson)

// Number - integers and decimals are the same type
const age = 25;
const price = 99.99;
const temperature = -5;

// Boolean - true or false
const isLoggedIn = true;
const hasPermission = false;

// Null - intentionally empty ("I know there's nothing here")
const selectedItem = null;

// Undefined - not yet assigned ("This hasn't been set")
let userInput;
console.log(userInput); // undefined
```

That's it. No `int` vs `float`, no `str` vs `bytes`. JavaScript keeps it simpler than Python in this regard.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // One number type for everything
    const count = 42;
    const price = 19.99;
    const negative = -10;

    typeof count; // "number"
    typeof price; // "number"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Separate int and float types
    count = 42
    price = 19.99
    negative = -10

    type(count)  # <class 'int'>
    type(price)  # <class 'float'>
    ```
  </Tab>
</Tabs>

### null vs undefined

This is the one part that trips up Python developers. Python has `None`. JavaScript has two "nothing" values:

```javascript theme={null}
// null = you explicitly set it to "nothing"
let selectedUser = null; // "No user selected yet"

// undefined = JavaScript set it because nothing was assigned
let searchQuery;
console.log(searchQuery); // undefined - "This variable exists but has no value"
```

<Tip>
  Use `null` when you want to intentionally say "empty" or "no value." Let `undefined` be JavaScript's default for "not yet assigned." In practice, you'll mostly use `null`.
</Tip>

## Type checking

Use `typeof` to check what type a value is. This is especially useful when debugging or validating API responses.

```javascript theme={null}
typeof "Sarah";       // "string"
typeof 42;           // "number"
typeof true;         // "boolean"
typeof undefined;    // "undefined"
typeof null;         // "object"  ← This is a bug. Seriously.
typeof { name: "Sarah" }; // "object"
typeof [1, 2, 3];   // "object"  ← Arrays are objects too
```

<Warning>
  `typeof null` returns `"object"` instead of `"null"`. This is a well-known bug from 1995 that was never fixed because too much code depends on it. To check for null, use `value === null` instead.
</Warning>

```javascript theme={null}
// Checking for null properly
const selectedUser = null;

// ❌ Wrong: typeof doesn't help
console.log(typeof selectedUser); // "object"

// ✅ Correct: Direct comparison
console.log(selectedUser === null); // true
```

To check if something is an array, use `Array.isArray()`:

```javascript theme={null}
const users = ["Sarah", "John", "Alice"];
const user = { name: "Sarah" };

Array.isArray(users); // true
Array.isArray(user);  // false
```

## Type coercion

JavaScript tries to be "helpful" by automatically converting types when you mix them. This leads to some genuinely weird behavior.

```javascript theme={null}
// JavaScript automatically converts types
console.log("5" + 3);     // "53"  (number becomes string)
console.log("5" - 3);     // 2     (string becomes number)
console.log("5" * 2);     // 10    (string becomes number)
console.log(true + 1);    // 2     (true becomes 1)
console.log(false + 1);   // 1     (false becomes 0)
console.log("" == false); // true  (both coerced to 0)
```

The `+` operator is particularly tricky — if either side is a string, it concatenates instead of adding. The other math operators (`-`, `*`, `/`) convert strings to numbers.

<Warning>
  Don't rely on type coercion. Always convert types explicitly when you need to. Implicit coercion causes bugs that are hard to track down.
</Warning>

### Converting types explicitly

```javascript theme={null}
// String to number
const input = "42";
const count = Number(input);
console.log(count);        // 42
console.log(typeof count); // "number"

// Number to string
const price = 99.99;
const label = String(price);
console.log(label);        // "99.99"
console.log(typeof label); // "string"

// Anything to boolean
Boolean(0);         // false
Boolean("");        // false
Boolean(null);      // false
Boolean(undefined); // false
Boolean("hello");   // true
Boolean(42);        // true
Boolean([]);        // true  ← Empty arrays are truthy!
```

<Info>
  Values that convert to `false` are called "falsy": `0`, `""`, `null`, `undefined`, `NaN`, and `false`. Everything else is "truthy." You'll use this concept constantly in React for conditional rendering.
</Info>

## Equality: == vs ===

This is the most important syntax rule in this entire lesson.

```javascript theme={null}
// == (loose equality) - converts types before comparing
console.log(5 == "5");    // true  (string "5" converted to number 5)
console.log(0 == false);  // true  (false converted to 0)
console.log("" == false); // true  (both converted to 0)
console.log(null == undefined); // true

// === (strict equality) - no type conversion, must match exactly
console.log(5 === "5");    // false (different types)
console.log(0 === false);  // false (different types)
console.log("" === false); // false (different types)
console.log(null === undefined); // false (different types)
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Always use === in JavaScript
    const userAge = "25";
    const minAge = 25;

    if (userAge === minAge) {
      console.log("Match"); // Won't run - different types
    }

    if (Number(userAge) === minAge) {
      console.log("Match"); // Runs - both are numbers now
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Python's == already works like JavaScript's ===
    user_age = "25"
    min_age = 25

    if user_age == min_age:
        print("Match")  # Won't run - Python doesn't coerce
    ```
  </Tab>
</Tabs>

<Tip>
  Always use `===` and `!==`. Pretend `==` and `!=` don't exist. This is the universal recommendation from every JavaScript style guide, linter, and senior developer.
</Tip>

## Common mistakes

<AccordionGroup>
  <Accordion title="Using == instead of ===">
    ```javascript theme={null}
    // ❌ Wrong: Loose equality causes unexpected matches
    const status = 0;
    if (status == false) {
      console.log("No status"); // Runs! 0 is coerced to false
    }

    // ✅ Correct: Strict equality
    const status = 0;
    if (status === false) {
      console.log("No status"); // Doesn't run - 0 is not false
    }
    if (status === 0) {
      console.log("Status is zero"); // Runs - exact match
    }
    ```

    <Warning>
      `==` converts types before comparing, which leads to surprising results like `0 == false` being `true`. Use `===` to compare both value and type.
    </Warning>
  </Accordion>

  <Accordion title="Confusing null and undefined">
    ```javascript theme={null}
    // ❌ Wrong: Treating them as interchangeable
    let data;
    if (data === null) {
      console.log("No data"); // Doesn't run! data is undefined, not null
    }

    // ✅ Correct: Check for both, or use the right one
    let data;
    if (data == null) {
      console.log("No data"); // Runs - == treats null and undefined as equal
    }

    // Or be explicit:
    if (data === null || data === undefined) {
      console.log("No data"); // Runs
    }
    ```

    <Warning>
      `undefined` means "not yet assigned." `null` means "intentionally empty." They're not the same thing, but `==` treats them as equal. This is the one exception where `==` is sometimes preferred — checking for `null == undefined` catches both.
    </Warning>
  </Accordion>

  <Accordion title="Assuming typeof null returns 'null'">
    ```javascript theme={null}
    // ❌ Wrong: Checking null with typeof
    const result = null;
    if (typeof result === "null") {
      console.log("Result is null"); // Never runs!
    }

    // ✅ Correct: Direct comparison
    const result = null;
    if (result === null) {
      console.log("Result is null"); // Runs
    }
    ```

    <Warning>
      `typeof null` returns `"object"` due to a decades-old bug in JavaScript. Always check for null with `=== null`.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You know the building blocks — strings, numbers, booleans, and how to compare them safely. Next, let's look at a cleaner way to work with strings using template literals.

<Card title="Template literals" icon="quote-left" href="/javascript-core/template-literals">
  String interpolation, multi-line strings, and goodbye to string concatenation
</Card>


# Functions basics
Source: https://js.maxbraglia.com/javascript-core/functions-basics

Write reusable blocks of code with JavaScript functions

## What are functions?

Functions are reusable blocks of code. You define them once and call them whenever you need that logic. If you've written `def` in Python, you already understand the concept — JavaScript just wraps it differently.

```javascript theme={null}
function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet("Sarah")); // "Hello, Sarah!"
console.log(greet("John"));  // "Hello, John!"
```

## Function declarations

The most common way to create a function:

```javascript theme={null}
function calculateTotal(price, taxRate) {
  const tax = price * taxRate;
  return price + tax;
}

const total = calculateTotal(99.99, 0.08);
console.log(total); // 107.9892
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    function calculateTotal(price, taxRate) {
      const tax = price * taxRate;
      return price + tax;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def calculate_total(price, tax_rate):
        tax = price * tax_rate
        return price + tax
    ```
  </Tab>
</Tabs>

The structure is identical — keyword, name, parameters, body, return. JavaScript uses `function` instead of `def`, curly braces instead of indentation, and `camelCase` instead of `snake_case`.

## Return values

Functions return `undefined` by default. If you want a value back, you need an explicit `return` statement.

```javascript theme={null}
function add(a, b) {
  return a + b; // Returns the sum
}

function logMessage(message) {
  console.log(message); // No return — returns undefined
}

const result = add(5, 3);
console.log(result); // 8
```

`return` also exits the function immediately. Code after `return` never runs.

```javascript theme={null}
function checkAge(age) {
  if (age < 18) {
    return "Too young";
  }
  return "Welcome"; // Only runs if age >= 18
}

console.log(checkAge(15)); // "Too young"
console.log(checkAge(25)); // "Welcome"
```

## Function expressions

You can also create functions by assigning them to variables:

```javascript theme={null}
const multiply = function(a, b) {
  return a * b;
};

console.log(multiply(4, 5)); // 20
```

This is called a **function expression**. The function doesn't have its own name — it's stored in the variable `multiply`.

<Info>
  Function declarations are "hoisted" — you can call them before they appear in your code. Function expressions are not. For now, stick with function declarations. You'll use function expressions more when you learn arrow functions next.
</Info>

## Functions as values

JavaScript relies much more heavily on functions as values in everyday programming patterns — but Python supports the same concept.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    function applyOperation(a, b, operation) {
      return operation(a, b);
    }

    function add(x, y) { return x + y; }
    function subtract(x, y) { return x - y; }

    console.log(applyOperation(10, 3, add));      // 13
    console.log(applyOperation(10, 3, subtract)); // 7
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Almost identical in Python
    def apply_operation(a, b, operation):
        return operation(a, b)

    def add(x, y):
        return x + y

    def subtract(x, y):
        return x - y

    print(apply_operation(10, 3, add))       # 13
    print(apply_operation(10, 3, subtract))  # 7
    ```
  </Tab>
</Tabs>

You'll use this pattern constantly. Array methods like `.map()`, `.filter()`, and `.forEach()` all take functions as arguments. React event handlers work the same way.

<Tip>
  Get comfortable with passing functions as arguments. It's one of the most common patterns in JavaScript and React. You'll see it everywhere: `array.map(myFunction)`, `button.addEventListener("click", myFunction)`, `<button onClick={myFunction}>`.
</Tip>

## Calling vs referencing

A subtle but important distinction:

```javascript theme={null}
function sayHello() {
  return "Hello!";
}

// Calling the function — runs it, gives you the result
console.log(sayHello()); // "Hello!"

// Referencing the function — passes the function itself
console.log(sayHello); // [Function: sayHello]
```

With parentheses `()` you **call** the function. Without parentheses, you **reference** it. This matters when passing functions to event handlers or array methods — you pass the reference, not the result.

```javascript theme={null}
// ✅ Correct: Pass the function reference
button.addEventListener("click", handleClick);

// ❌ Wrong: This CALLS handleClick immediately
button.addEventListener("click", handleClick());
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting to return a value">
    ```javascript theme={null}
    // ❌ Wrong: Missing return
    function calculateTax(price) {
      const tax = price * 0.08;
      // Forgot to return! Returns undefined
    }

    const tax = calculateTax(100);
    console.log(tax); // undefined

    // ✅ Correct: Include return
    function calculateTax(price) {
      const tax = price * 0.08;
      return tax;
    }
    ```

    <Warning>
      If your function computes a value but doesn't `return` it, you get `undefined`. This is one of the most common bugs in JavaScript — especially for Python developers, since Python returns `None` explicitly.
    </Warning>
  </Accordion>

  <Accordion title="Calling a function reference instead of passing it">
    ```javascript theme={null}
    // ❌ Wrong: Calls immediately, passes the return value
    setTimeout(doSomething(), 1000);

    // ✅ Correct: Passes the function, called later
    setTimeout(doSomething, 1000);
    ```

    <Warning>
      When passing a function as an argument, don't add `()` unless you want it to run immediately. This trips up everyone at first — especially in React's `onClick` handlers.
    </Warning>
  </Accordion>

  <Accordion title="Semicolon after function declarations">
    ```javascript theme={null}
    // Function declarations — no semicolon needed
    function greet(name) {
      return `Hello, ${name}!`;
    }

    // Function expressions — semicolon after the assignment
    const greet = function(name) {
      return `Hello, ${name}!`;
    };
    ```

    <Warning>
      Function declarations don't end with a semicolon (they're statements). Function expressions do (they're assignments). This is a minor style point — Prettier handles it automatically if you have it set up.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You know how to write and call functions. JavaScript has a shorter, more modern syntax for functions called arrow functions — you'll use them everywhere in React.

<Card title="Arrow functions" icon="arrow-right" href="/javascript-core/arrow-functions">
  Write shorter, cleaner functions with the modern syntax
</Card>


# JavaScript basics
Source: https://js.maxbraglia.com/javascript-core/overview

What JavaScript is, how it fits into web development, and essential syntax

## What is JavaScript?

JavaScript is the programming language of the web. Every interactive website you've ever used — clicking buttons, loading new data without refreshing, updating a shopping cart — that's JavaScript running in the browser.

```javascript theme={null}
// This runs in the browser
document.querySelector("button").addEventListener("click", () => {
  console.log("Button clicked!");
});

// This runs on the server (with Node.js)
const express = require("express");
const app = express();
app.listen(3000);
```

JavaScript started as a browser-only language in 1995. Today it runs everywhere — browsers, servers (Node.js), mobile apps, and even desktop applications. For web development, it's not optional. HTML gives you structure, CSS gives you style, and JavaScript gives you behavior.

<Info>
  In this course, you'll use JavaScript for two things: building React frontends and connecting them to your FastAPI backend. That covers the vast majority of what full-stack web developers do with JavaScript.
</Info>

## JavaScript vs Python

You already know how to program. JavaScript and Python share the same core concepts — variables, functions, loops, objects. The differences are mostly syntax.

```javascript theme={null}
// JavaScript
function greetUser(name) {
  const message = `Hello, ${name}!`;
  console.log(message);
  return message;
}

const users = ["Sarah", "John", "Alice"];

for (const user of users) {
  greetUser(user);
}
```

```python theme={null}
# Python equivalent
def greet_user(name):
    message = f"Hello, {name}!"
    print(message)
    return message

users = ["Sarah", "John", "Alice"]

for user in users:
    greet_user(user)
```

The logic is identical. The wrapping is different. Here are the key differences you'll notice right away:

| Feature   | Python             | JavaScript               |
| --------- | ------------------ | ------------------------ |
| Variables | `name = "Sarah"`   | `const name = "Sarah";`  |
| Functions | `def greet():`     | `function greet() {}`    |
| Blocks    | Indentation        | Curly braces `{}`        |
| Strings   | `f"Hello, {name}"` | `` `Hello, ${name}` ``   |
| Print     | `print()`          | `console.log()`          |
| None/null | `None`             | `null` (and `undefined`) |
| Naming    | `snake_case`       | `camelCase`              |

<Tip>
  Don't try to memorize every difference up front. You'll pick them up naturally as you write code. The table above covers 90% of what trips people up in the first few days.
</Tip>

## Syntax basics

JavaScript has three syntax rules that differ from Python. Once you internalize these, the rest feels familiar.

### Semicolons

```javascript theme={null}
const name = "Sarah";
const age = 25;
console.log(name); // "Sarah"
```

Semicolons end each statement. JavaScript can technically guess where they go (called "automatic semicolon insertion"), but always include them. It avoids subtle bugs and every serious codebase uses them.

### Curly braces

```javascript theme={null}
// Python uses indentation
// JavaScript uses curly braces {}

function calculateTotal(price, taxRate) {
  const tax = price * taxRate;
  const total = price + tax;
  return total;
}

if (total > 100) {
  console.log("Free shipping!");
} else {
  console.log("Shipping: $9.99");
}
```

Curly braces `{}` define blocks of code — function bodies, if/else branches, loops. Indentation is optional (but you should still indent for readability).

### Case sensitivity

```javascript theme={null}
const userName = "Sarah";
const UserName = "John";
const USERNAME = "ALICE";

// These are three different variables
console.log(userName); // "Sarah"
console.log(UserName); // "John"
console.log(USERNAME); // "ALICE"
```

JavaScript is case-sensitive. `userName`, `UserName`, and `USERNAME` are three completely different variables. The convention is `camelCase` for most things, `PascalCase` for React components, and `UPPER_CASE` for constants.

### Comments

```javascript theme={null}
// Single-line comment

/*
  Multi-line comment
  for longer explanations
*/

const apiUrl = "https://api.example.com"; // Inline comment
```

Two slashes `//` for single-line comments, `/* */` for multi-line. Same idea as Python's `#`, just different characters.

## Running JavaScript

You'll run JavaScript in two places during this course:

### Browser console (for quick experiments)

Open any browser, press `F12` (or `Cmd+Option+J` on Mac), and type directly into the Console tab.

```javascript theme={null}
// Try this in your browser console right now
const greeting = "Hello from JavaScript!";
console.log(greeting); // "Hello from JavaScript!"
```

### Node.js (for files and projects)

Create a `.js` file and run it with Node:

```javascript hello.js theme={null}
const name = "Sarah";
console.log(`Welcome to JavaScript, ${name}!`);
```

```bash theme={null}
node hello.js
# Welcome to JavaScript, Sarah!
```

<Tip>
  Use the browser console to test quick ideas and one-liners. Use Node.js for anything you want to save or build on. You set up Node.js in the Getting Started section.
</Tip>

## What's next?

Now that you know how JavaScript fits into web development and how its syntax compares to Python, let's start writing real code. First up: storing data in variables.

<Card title="Variables" icon="box" href="/javascript-core/variables">
  Store and manage data using let and const
</Card>


# Parameters and arguments
Source: https://js.maxbraglia.com/javascript-core/parameters-arguments

Pass data into functions with default values and destructuring

## Parameters vs arguments

A quick terminology note: **parameters** are the variables in the function definition. **Arguments** are the actual values you pass when calling the function.

```javascript theme={null}
// "name" and "age" are parameters
function createUser(name, age) {
  return { name, age };
}

// "Sarah" and 28 are arguments
const user = createUser("Sarah", 28);
console.log(user); // { name: "Sarah", age: 28 }
```

In practice, people use the terms interchangeably. Don't worry about it.

<Info>
  Python mental model: JavaScript is more permissive than Python here. If you pass too few arguments, the missing ones become `undefined` (instead of raising a `TypeError`). If you pass extra arguments, JavaScript ignores them unless you collect them with a rest parameter (`...args`).
</Info>

## Default parameters

Give parameters a fallback value when no argument is provided:

```javascript theme={null}
function greet(name, greeting = "Hello") {
  return `${greeting}, ${name}!`;
}

console.log(greet("Sarah"));           // "Hello, Sarah!"
console.log(greet("Sarah", "Hey"));    // "Hey, Sarah!"
console.log(greet("Sarah", "Welcome")); // "Welcome, Sarah!"
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    function createUser(name, role = "viewer") {
      return { name, role };
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def create_user(name, role="viewer"):
        return {"name": name, "role": role}
    ```
  </Tab>
</Tabs>

Same concept, same position — defaults go in the parameter list. JavaScript uses `=`, Python uses `=`. No surprises here.

<Tip>
  One important JavaScript difference: default parameters are used when the argument is missing **or explicitly `undefined`**. Passing `null` does **not** use the default.
</Tip>

### Practical example

```javascript theme={null}
async function fetchUsers(page = 1, limit = 10) {
  const response = await fetch(
    `http://localhost:8000/api/users?page=${page}&limit=${limit}`
  );
  return response.json();
}

// Use defaults
const firstPage = await fetchUsers();

// Override both
const thirdPage = await fetchUsers(3, 25);
```

<Tip>
  Put required parameters first, optional parameters (with defaults) last. This is the same convention as Python.
</Tip>

## Rest parameters

Collect any number of arguments into an array using `...`:

```javascript theme={null}
function sum(...numbers) {
  return numbers.reduce((total, n) => total + n, 0);
}

console.log(sum(1, 2, 3));       // 6
console.log(sum(10, 20, 30, 40)); // 100
```

The rest parameter `...numbers` gathers all arguments into a real array. You can then use array methods on it.

```javascript theme={null}
function logAll(label, ...items) {
  console.log(`${label}:`);
  items.forEach(item => console.log(`  - ${item}`));
}

logAll("Fruits", "Apple", "Banana", "Cherry");
// Fruits:
//   - Apple
//   - Banana
//   - Cherry
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    function sum(...numbers) {
      return numbers.reduce((total, n) => total + n, 0);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def sum(*numbers):
        return sum(numbers)  # Built-in sum works on tuples
    ```
  </Tab>
</Tabs>

JavaScript uses `...args`, Python uses `*args`. Same idea.

<Info>
  In JavaScript, `...` is used in multiple places (rest parameters, spread syntax). In Python, `*args` and `**kwargs` are split into separate syntaxes/uses. Same family of idea, different syntax rules.
</Info>

<Warning>
  The rest parameter must be the last parameter. `function bad(...args, last)` is a syntax error.
</Warning>

## Destructuring parameters

When a function takes an object, you can destructure it right in the parameter list:

```javascript theme={null}
// Without destructuring
function displayUser(user) {
  console.log(`${user.name} (${user.email})`);
}

// With destructuring — cleaner
function displayUser({ name, email }) {
  console.log(`${name} (${email})`);
}

const user = { name: "Sarah", email: "sarah@example.com", role: "admin" };
displayUser(user); // "Sarah (sarah@example.com)"
```

This is a pattern you'll see everywhere in React. Component props are destructured this way:

```jsx theme={null}
// React component with destructured props
function UserCard({ name, email, role }) {
  return (
    <div>
      <h2>{name}</h2>
      <p>{email}</p>
      <span>{role}</span>
    </div>
  );
}
```

### Destructuring with defaults

Combine destructuring and default values:

```javascript theme={null}
function createRequest({ method = "GET", url, body = null }) {
  console.log(`${method} ${url}`);
  if (body) console.log("Body:", body);
}

createRequest({ url: "http://localhost:8000/api/users" });
// "GET http://localhost:8000/api/users"

createRequest({ method: "POST", url: "/api/users", body: { name: "Sarah" } });
// "POST /api/users"
// "Body: { name: 'Sarah' }"
```

<Tip>
  Destructured parameters with defaults are the cleanest way to handle options objects. You'll see this pattern in API client functions, React components, and configuration.
</Tip>

<Tip>
  Python mental model: this is often nicer than passing a long list of positional args, and it plays a similar role to keyword-argument style APIs (`func(url=..., timeout=...)`) — but in JavaScript you're usually passing a single options object.
</Tip>

## What's next?

You know how to define functions and pass data into them. Next, let's understand *where* variables live — scope determines which parts of your code can see which variables.

<Card title="Understanding scope" icon="layer-group" href="/javascript-core/understanding-scope">
  How JavaScript determines where variables are accessible
</Card>


# Template literals
Source: https://js.maxbraglia.com/javascript-core/template-literals

Build dynamic strings with embedded expressions using backticks

## String interpolation

Template literals let you embed variables and expressions directly inside strings. If you've used Python's f-strings, this will feel instantly familiar.

```javascript theme={null}
const name = "Sarah";
const age = 28;

const message = `Hello, ${name}! You are ${age} years old.`;
console.log(message); // "Hello, Sarah! You are 28 years old."
```

The key difference from regular strings: template literals use **backticks** (`` ` ``), not quotes. Variables go inside `${}`.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const name = "Sarah";
    const role = "developer";

    const greeting = `Welcome, ${name}! You are a ${role}.`;
    console.log(greeting); // "Welcome, Sarah! You are a developer."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    name = "Sarah"
    role = "developer"

    greeting = f"Welcome, {name}! You are a {role}."
    print(greeting)  # "Welcome, Sarah! You are a developer."
    ```
  </Tab>
</Tabs>

Same concept, slightly different syntax. Backticks instead of `f"..."`, and `${}` instead of `{}`.

## Expressions inside template literals

You can put any JavaScript expression inside `${}` — math, function calls, ternary operators, method calls.

```javascript theme={null}
const price = 29.99;
const quantity = 3;

console.log(`Total: $${(price * quantity).toFixed(2)}`); // "Total: $89.97"
console.log(`Items: ${quantity > 1 ? "multiple" : "single"}`); // "Items: multiple"
console.log(`Uppercase: ${"hello".toUpperCase()}`); // "Uppercase: HELLO"
```

<Tip>
  Use `.toFixed(2)` to format numbers as currency with exactly 2 decimal places. You'll use this pattern constantly when displaying prices.
</Tip>

## Multi-line strings

Template literals preserve line breaks. No need for `\n` characters or string concatenation.

```javascript theme={null}
const userName = "Sarah";
const orderId = "ORD-2024-001";

const email = `
Hello ${userName},

Your order has been confirmed.
Order ID: ${orderId}

Thanks for your purchase!
`;

console.log(email);
```

This is much cleaner than the alternative:

```javascript theme={null}
// ❌ Without template literals — messy
const email = "Hello " + userName + ",\n\n" +
  "Your order has been confirmed.\n" +
  "Order ID: " + orderId + "\n\n" +
  "Thanks for your purchase!";
```

<Warning>
  Multi-line template literals preserve all whitespace, including indentation. If you indent the template literal inside a function, those spaces will appear in the output. Keep the content flush-left if spacing matters.
</Warning>

## Building HTML strings

You'll sometimes build HTML strings in JavaScript — especially before you learn React. Template literals make this readable.

```javascript theme={null}
const user = { name: "Sarah", email: "sarah@example.com", role: "Admin" };

const html = `
<div class="user-card">
  <h2>${user.name}</h2>
  <p>${user.email}</p>
  <span class="badge">${user.role}</span>
</div>
`;
```

<Info>
  Once you learn React in Section 7, you'll use JSX instead of building HTML strings. But it's useful to see this pattern first — it shows why template literals matter for web development.
</Info>

## Common mistakes

<AccordionGroup>
  <Accordion title="Using quotes instead of backticks">
    ```javascript theme={null}
    // ❌ Wrong: Regular quotes don't interpolate
    const name = "Sarah";
    const message = "Hello, ${name}!";
    console.log(message); // "Hello, ${name}!" (literal text)

    // ✅ Correct: Use backticks
    const message2 = `Hello, ${name}!`;
    console.log(message2); // "Hello, Sarah!"
    ```

    <Warning>
      Template literals **must** use backticks (`` ` ``). Single quotes `'...'` and double quotes `"..."` treat `${...}` as literal text.
    </Warning>
  </Accordion>

  <Accordion title="Forgetting the dollar sign">
    ```javascript theme={null}
    // ❌ Wrong: Missing $
    const name = "Sarah";
    const message = `Hello, {name}!`;
    console.log(message); // "Hello, {name}!"

    // ✅ Correct: Include $
    const message2 = `Hello, ${name}!`;
    console.log(message2); // "Hello, Sarah!"
    ```

    <Warning>
      Python f-strings use `{name}`. JavaScript template literals need `${name}` — don't forget the dollar sign.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can build dynamic strings. Before we move to functions, let's cover one quick topic — comments.

<Card title="Comments" icon="message" href="/javascript-core/comments">
  Add notes and documentation to your JavaScript code
</Card>


# Understanding scope
Source: https://js.maxbraglia.com/javascript-core/understanding-scope

Learn how JavaScript determines where variables are accessible

## What is scope?

Scope is the set of rules that determines where a variable can be accessed. When you declare a variable, it's only visible within a certain region of your code. Try to use it outside that region and you'll get an error.

```javascript theme={null}
function processOrder() {
  const orderId = "ORD-001";
  console.log(orderId); // ✅ Works — same scope
}

processOrder();
console.log(orderId); // ❌ ReferenceError: orderId is not defined
```

`orderId` exists inside `processOrder` and nowhere else. This is a good thing — it means variables don't leak into places they shouldn't be.

<Info>
  Python mental model: this is the same general idea as Python scope (LEGB: Local, Enclosing, Global, Built-in). The biggest difference you'll feel in JavaScript is that `let`/`const` also create **block scope** for `if`/`for`/`while`.
</Info>

## Block scope

Variables declared with `const` and `let` are **block-scoped**. They exist only within the nearest set of curly braces `{}`.

```javascript theme={null}
if (true) {
  const message = "Inside the block";
  let count = 42;
  console.log(message); // ✅ "Inside the block"
  console.log(count);   // ✅ 42
}

console.log(message); // ❌ ReferenceError
console.log(count);   // ❌ ReferenceError
```

Every `if`, `for`, `while`, and function body creates a new block scope:

```javascript theme={null}
for (let i = 0; i < 3; i++) {
  const item = `Item ${i}`;
  console.log(item); // ✅ Works inside the loop
}

console.log(i);    // ❌ ReferenceError
console.log(item); // ❌ ReferenceError
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Block-scoped — each block is its own world
    if (true) {
      const x = 10;
    }
    console.log(x); // ReferenceError
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Python doesn't have block scope for if/for
    if True:
        x = 10
    print(x)  # 10 — still accessible!
    ```
  </Tab>
</Tabs>

This is a real difference from Python. In Python, `if` and `for` blocks don't create their own scope — variables leak out. In JavaScript, they don't.

<Warning>
  If you're used to Python, this will trip you up. Variables declared inside `if`, `for`, or `while` blocks in JavaScript are **not** accessible outside those blocks. This is actually safer — it prevents accidental name collisions.
</Warning>

## Function scope

Functions create their own scope. Variables declared inside a function are invisible outside it.

```javascript theme={null}
function calculateDiscount(price) {
  const discountRate = 0.15;
  const discount = price * discountRate;
  return price - discount;
}

console.log(calculateDiscount(100)); // 85
console.log(discountRate); // ❌ ReferenceError
console.log(discount);     // ❌ ReferenceError
```

Nested functions can access variables from their parent function:

```javascript theme={null}
function outer() {
  const outerVar = "I'm from outer";

  function inner() {
    const innerVar = "I'm from inner";
    console.log(outerVar); // ✅ Can see parent's variables
    console.log(innerVar); // ✅ Can see own variables
  }

  inner();
  console.log(innerVar); // ❌ Can't see child's variables
}
```

This is called **lexical scoping** — inner functions can look "up" to their parent's scope, but parents can't look "down" into children.

<Tip>
  This part is very similar to Python: nested functions can read variables from outer functions. That's the foundation for closures in both languages.
</Tip>

## Global scope

Variables declared outside any function or block are in the **global scope**. They're accessible everywhere.

```javascript theme={null}
const API_URL = "http://localhost:8000"; // Global

function fetchData() {
  console.log(API_URL); // ✅ Works — global is visible everywhere
}

function sendData() {
  console.log(API_URL); // ✅ Also works
}
```

<Tip>
  Keep global variables to a minimum. Use them for true constants like API URLs and configuration values. Everything else should live in the smallest scope possible.
</Tip>

## Scope chain

When JavaScript encounters a variable, it searches from the current scope outward:

```javascript theme={null}
const color = "blue"; // Global

function paintRoom() {
  const color = "green"; // Function scope — shadows the global

  if (true) {
    const color = "red"; // Block scope — shadows the function scope
    console.log(color);  // "red"
  }

  console.log(color); // "green"
}

paintRoom();
console.log(color); // "blue"
```

Each `color` is a different variable in a different scope. The inner-most scope wins. This is called **variable shadowing**.

<Info>
  Python mental model: same idea as name shadowing in nested scopes — a local variable named `color` hides an outer `color`. JavaScript's scope chain and Python's LEGB rule are solving the same problem.
</Info>

<Info>
  Variable shadowing is legal but can be confusing. Avoid reusing the same variable name in nested scopes. ESLint can warn you about this with the `no-shadow` rule.
</Info>

## Common mistakes

<AccordionGroup>
  <Accordion title="Accessing a block-scoped variable outside its block">
    ```javascript theme={null}
    // ❌ Wrong: Variable only exists inside the if block
    if (userIsLoggedIn) {
      const welcomeMessage = `Welcome back, ${userName}!`;
    }
    console.log(welcomeMessage); // ReferenceError

    // ✅ Correct: Declare it in the outer scope
    let welcomeMessage = "";
    if (userIsLoggedIn) {
      welcomeMessage = `Welcome back, ${userName}!`;
    }
    console.log(welcomeMessage); // Works
    ```

    <Warning>
      If you need a variable after a block ends, declare it before the block with `let`. You can assign the value inside the block.
    </Warning>
  </Accordion>

  <Accordion title="Hoisting confusion with var">
    ```javascript theme={null}
    // var is hoisted and function-scoped — avoid it
    console.log(name); // undefined (not an error!)
    var name = "Sarah";

    // const and let are NOT hoisted the same way
    console.log(name); // ReferenceError: Cannot access before initialization
    const name = "Sarah";
    ```

    <Warning>
      `var` has confusing hoisting behavior — it exists before its declaration but with the value `undefined`. This is one of the main reasons the JavaScript community moved to `const` and `let`. Stick with `const` and `let` and you'll never deal with hoisting issues.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You understand how scope works — variables live inside blocks and functions, and inner scopes can see outer scopes. This leads directly to one of JavaScript's most useful features: closures.

<Card title="Closures" icon="lock" href="/javascript-core/closures">
  How functions remember their surrounding variables
</Card>


# Variables
Source: https://js.maxbraglia.com/javascript-core/variables

Store and manage data in your JavaScript programs using let and const

## What are variables?

Variables store data that you'll use throughout your program - user input, API responses, calculation results, and more.

JavaScript has two ways to declare variables: `let` for values that change, and `const` for values that don't.

## Declaring variables

```javascript theme={null}
// Use const for values that won't change
const apiUrl = "https://api.example.com";
const maxRetries = 3;
const user = { name: "Sarah", email: "sarah@example.com" };

// Use let for values that will change
let userInput = "";
let attemptCount = 0;
let isLoading = false;
```

`const` prevents reassignment - once you set a value, you can't change it. `let` allows the value to be updated later.

<Tip>
  Default to `const` unless you know the value needs to change. This prevents accidental reassignments and makes your code easier to understand.
</Tip>

## Updating variables

```javascript theme={null}
let count = 0;
console.log(count); // 0

count = 5;
console.log(count); // 5

count = count + 1;
console.log(count); // 6

// Shorthand
count += 10;
console.log(count); // 16
```

With `let`, you can reassign the variable as many times as needed. Use `+=`, `-=`, `*=`, `/=` for arithmetic shortcuts.

## Naming conventions

```javascript theme={null}
// Use camelCase for variable names
const firstName = "Sarah";
const userEmail = "sarah@example.com";
const isLoggedIn = true;
const totalPrice = 99.99;

// Use UPPER_CASE for constants that never change
const API_KEY = "abc123xyz";
const MAX_FILE_SIZE = 5000000;
const DEFAULT_TIMEOUT = 30000;
```

Start with a lowercase letter, then capitalize the first letter of each new word. For true constants (values that never change across your entire app), use UPPER\_CASE with underscores.

<Info>
  JavaScript variable names can contain letters, numbers, underscores, and dollar signs - but they can't start with a number.
</Info>

## Variable scope

```javascript theme={null}
const globalVar = "I'm available everywhere";

function myFunction() {
  const functionVar = "I only exist inside this function";
  
  if (true) {
    const blockVar = "I only exist inside this if block";
    let anotherBlockVar = "Me too!";
    
    console.log(globalVar);      // Works
    console.log(functionVar);    // Works
    console.log(blockVar);       // Works
  }
  
  console.log(blockVar);  // Error: blockVar is not defined
}
```

Variables declared with `const` and `let` are "block-scoped" - they only exist within the nearest set of curly braces `{}`.

<Tip>
  Keep variables in the smallest scope possible. This makes your code easier to debug and prevents naming conflicts.
</Tip>

## Comparing to Python

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // JavaScript uses const/let
    const name = "Sarah";
    let age = 25;

    age = 26; // Can reassign let
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Python doesn't have const
    name = "Sarah"
    age = 25

    age = 26  # Can always reassign
    ```
  </Tab>
</Tabs>

Python doesn't distinguish between changeable and unchangeable variables - everything can be reassigned. JavaScript's `const` helps you catch bugs by preventing accidental reassignments.

## Common mistakes

<AccordionGroup>
  <Accordion title="Trying to reassign a const">
    ```javascript theme={null}
    // ❌ Wrong: Can't reassign const
    const name = "Sarah";
    name = "John"; // TypeError: Assignment to constant variable

    // ✅ Correct: Use let if you need to reassign
    let name = "Sarah";
    name = "John"; // Works fine
    ```

    <Warning>
      `const` prevents reassignment, but it doesn't make objects or arrays immutable. You can still modify properties or add items - you just can't reassign the entire variable.
    </Warning>
  </Accordion>

  <Accordion title="Thinking const makes objects immutable">
    ```javascript theme={null}
    // This is actually OK with const:
    const user = { name: "Sarah", age: 25 };
    user.age = 26; // Modifying a property works
    user.email = "sarah@example.com"; // Adding a property works

    // This is what const prevents:
    user = { name: "John" }; // TypeError: Assignment to constant variable

    // Same with arrays:
    const numbers = [1, 2, 3];
    numbers.push(4); // Adding to array works
    numbers = [5, 6, 7]; // TypeError: Assignment to constant variable
    ```

    <Warning>
      `const` only prevents reassigning the variable itself. You can still modify the contents of objects and arrays.
    </Warning>
  </Accordion>

  <Accordion title="Using var instead of let/const">
    ```javascript theme={null}
    // ❌ Wrong: var has confusing scoping rules
    var count = 0;

    // ✅ Correct: Always use let or const
    let count = 0;
    ```

    <Warning>
      `var` is the old way of declaring variables. It has weird scoping rules and can cause bugs. Pretend it doesn't exist - always use `let` or `const`.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

Now that you can store data in variables, let's learn about the different types of data JavaScript can handle.

<Card title="Data types" icon="cube" href="/javascript-core/data-types">
  Numbers, strings, booleans, and more
</Card>


# Course wrap-up
Source: https://js.maxbraglia.com/next-steps/course-wrap-up

Review what you've learned and how it all connects

## You built a full-stack web application

That's not a small thing. Let's look at what you actually learned:

| Section               | What you learned                                                     |
| --------------------- | -------------------------------------------------------------------- |
| **JavaScript Core**   | Variables, functions, arrow functions, scope, closures               |
| **Working with Data** | Arrays, objects, destructuring, spread, JSON, conditionals, loops    |
| **Async & APIs**      | Promises, async/await, fetch, error handling, loading states         |
| **DOM & Browser**     | Selecting elements, events, forms, localStorage                      |
| **React Essentials**  | Components, props, state, effects, lists, forms, composition         |
| **Full-Stack**        | Project structure, CORS, API client, CRUD operations, error handling |

That's a lot of ground. But here's what matters: **you can now build real web applications.** Not toy examples — actual apps that fetch data from an API, display it, let users create/edit/delete records, handle errors, and show loading states.

## How it all connects

```
User clicks a button
  → React handles the event (DOM & Browser + React Essentials)
  → Calls an API function (Async & APIs + Full-Stack)
  → fetch() sends request to FastAPI (Full-Stack)
  → FastAPI validates with Pydantic and returns JSON (Full-Stack)
  → React updates state with the response (React Essentials)
  → Component re-renders with new data (React Essentials)
  → User sees the updated UI
```

Every section built on the one before it. JavaScript Core gave you the language. Working with Data gave you the tools to transform data. Async & APIs taught you to talk to servers. React gave you the UI layer. Full-Stack wired it all together.

## What you can build now

With what you've learned, you can build:

* **Admin dashboards** — CRUD interfaces for managing data
* **User-facing apps** — registration, profiles, settings pages
* **Data display apps** — fetching from APIs and rendering lists/charts
* **Internal tools** — forms, tables, search/filter interfaces
* **Portfolio projects** — anything that reads and writes data

These aren't theoretical. The patterns you learned — `useState`, `useEffect`, `fetch`, loading/error/data, API client layer, CRUD state updates — are the exact same patterns used in production applications at companies of every size.

## The three CRUD state updates

If you remember nothing else, remember these:

```jsx theme={null}
// CREATE — add to the end
setItems(prev => [...prev, newItem]);

// UPDATE — replace the matching item
setItems(prev => prev.map(item => item.id === updated.id ? updated : item));

// DELETE — remove the matching item
setItems(prev => prev.filter(item => item.id !== deletedId));
```

These three lines power every data-driven React application.

## You're ready

The hardest part of learning JavaScript as a Python developer isn't the syntax — it's believing you can do it. You've already done it. You've written components, fetched data, handled errors, and built a full-stack app.

The next time you look at a React codebase, you'll recognize the patterns. `useState`, `useEffect`, `.map()` with keys, controlled forms, API client files — you know what all of this does now.

Keep building. Every new project reinforces what you've learned and teaches you something new.

<Card title="The essential 20%" icon="star" href="/next-steps/the-essential-20-percent">
  A quick reference of the JavaScript concepts you'll use 80% of the time
</Card>


# Deployment basics
Source: https://js.maxbraglia.com/next-steps/deployment-basics

Get your full-stack application live on the internet

## Two deployments, not one

Just like development, your frontend and backend deploy separately. Different platforms, different processes — but they connect the same way: the frontend makes HTTP requests to the backend's URL.

```
Development:
  Frontend → localhost:5173
  Backend  → localhost:8000

Production:
  Frontend → myapp.vercel.app
  Backend  → myapp-api.railway.app
```

## Deploy the frontend (React)

React builds to static files — HTML, CSS, and JavaScript. Any static hosting platform can serve them.

### Build for production

```bash theme={null}
cd frontend
npm run build
```

This creates a `dist/` folder with your optimized app. That's what gets deployed.

### Vercel (recommended)

The easiest way to deploy a React app. Connects to your GitHub repo and deploys automatically on every push.

<Steps>
  <Step title="Push your code to GitHub">
    Make sure your `frontend/` folder is in a GitHub repository.
  </Step>

  <Step title="Sign up at vercel.com">
    Sign in with your GitHub account.
  </Step>

  <Step title="Import your repository">
    Click "New Project" → select your repo → set the root directory to `frontend/`.
  </Step>

  <Step title="Add environment variables">
    In project settings, add `VITE_API_URL` with your backend's production URL.
  </Step>

  <Step title="Deploy">
    Vercel builds and deploys automatically. You get a URL like `myapp.vercel.app`.
  </Step>
</Steps>

### Netlify (alternative)

Same idea as Vercel. Connect GitHub, set build command to `npm run build`, publish directory to `dist/`.

<Info>
  Both Vercel and Netlify have generous free tiers. For personal projects and portfolios, you won't need to pay.
</Info>

## Deploy the backend (FastAPI)

Your Python backend needs a server that can run a process. This is different from static hosting — it's running actual code.

### Railway (recommended)

<Steps>
  <Step title="Push your backend to GitHub">
    Make sure your `backend/` folder has a `requirements.txt` with all dependencies.
  </Step>

  <Step title="Sign up at railway.app">
    Sign in with your GitHub account.
  </Step>

  <Step title="New project → Deploy from GitHub repo">
    Select your repo and set the root directory to `backend/`.
  </Step>

  <Step title="Add a start command">
    Set the start command to: `uvicorn main:app --host 0.0.0.0 --port $PORT`
  </Step>

  <Step title="Add environment variables">
    Add `DATABASE_URL`, `SECRET_KEY`, `ALLOWED_ORIGINS` (set to your frontend's production URL).
  </Step>

  <Step title="Deploy">
    Railway builds and deploys. You get a URL like `myapp-api.up.railway.app`.
  </Step>
</Steps>

### Render (alternative)

Similar to Railway. Create a new "Web Service," connect your GitHub repo, set the start command, add environment variables.

### Requirements file

Make sure your `requirements.txt` is complete:

```txt theme={null}
fastapi
uvicorn[standard]
python-dotenv
```

Add any other packages your backend uses (SQLAlchemy, httpx, etc.).

## Environment variables in production

This is where the `.env` pattern from the course pays off. In development, you read from `.env` files. In production, you set environment variables in your hosting platform's dashboard.

<Tabs>
  <Tab title="Frontend (Vercel)">
    ```
    VITE_API_URL=https://myapp-api.up.railway.app
    ```

    Set in Vercel → Project Settings → Environment Variables.
  </Tab>

  <Tab title="Backend (Railway)">
    ```
    DATABASE_URL=postgresql://...
    SECRET_KEY=your-production-secret
    ALLOWED_ORIGINS=https://myapp.vercel.app
    ```

    Set in Railway → Project → Variables.
  </Tab>
</Tabs>

<Warning>
  Update `ALLOWED_ORIGINS` on your backend to include your frontend's production URL. Without this, CORS will block all requests — the exact same error from the CORS lesson, but in production.
</Warning>

## The deployment checklist

Before deploying, verify:

* [ ] `npm run build` completes without errors (frontend)
* [ ] `requirements.txt` includes all Python packages (backend)
* [ ] Environment variables are set in both platforms
* [ ] `ALLOWED_ORIGINS` includes your frontend's production URL
* [ ] `.env` files are NOT committed to Git
* [ ] Backend start command uses `--host 0.0.0.0` (not localhost)

## After deployment

Test your production app:

1. Open your frontend URL in a browser
2. Open DevTools → Network tab
3. Check that API requests go to your production backend URL
4. Test all CRUD operations
5. Check the Console for any errors

<Tip>
  If something works locally but not in production, it's almost always one of three things: wrong `VITE_API_URL`, missing `ALLOWED_ORIGINS`, or a missing environment variable. Check these first.
</Tip>

## What's next?

Your app is live on the internet. One more lesson — where to get help when you're stuck.

<Card title="Get help" icon="comments" href="/next-steps/get-help">
  Join the community, ask questions, and keep learning
</Card>


# Get help
Source: https://js.maxbraglia.com/next-steps/get-help

Join the community, ask questions, and contribute to the course

## You will get stuck. That's normal.

Every developer — beginner and senior — gets stuck regularly. The difference isn't whether you get stuck, it's knowing where to look and how to ask. Here's your toolkit.

## Where to look first

Before asking anyone, try these in order:

<Steps>
  <Step title="Read the error message">
    JavaScript error messages are usually clear. `Cannot read properties of undefined (reading 'name')` means something is `undefined` when you expected an object. Read the message, check the line number.
  </Step>

  <Step title="Check the browser DevTools">
    Console tab for JavaScript errors. Network tab for API request/response issues. Elements tab for what's actually rendered.
  </Step>

  <Step title="console.log() the data">
    Add `console.log(data)` before the line that breaks. Check if the data is what you expect. This solves 80% of bugs.
  </Step>

  <Step title="Search the error message">
    Copy the error message (without your specific file paths) and paste it into Google. Chances are someone has already solved this exact problem.
  </Step>
</Steps>

<Tip>
  When you Google an error, add the technology name. "Cannot read properties of undefined React" gets better results than just the error message alone.
</Tip>

## Where to ask questions

### Stack Overflow

The largest Q\&A site for developers. Search first — your question has almost certainly been asked before.

When asking a new question:

* Include the **error message** (exact text)
* Include the **relevant code** (minimal reproduction)
* Describe what you **expected** vs what **happened**
* Mention what you've **already tried**

### MDN Web Docs

Not just a reference — MDN has explanations, examples, and browser compatibility tables for every JavaScript feature. When you're confused about how something works, MDN is the answer.

### React docs

The new React docs at `react.dev` have interactive examples you can edit and run directly in the browser. If you're confused about a React concept, the docs probably have a tutorial for it.

## Asking good questions

The quality of help you get depends on the quality of your question. Here's the formula:

```
1. What I'm trying to do:       "I'm trying to fetch users and display them in a list"
2. What I expected to happen:    "The list should show 3 users from the API"
3. What actually happened:       "The page shows 'Loading...' forever"
4. The error message (if any):   "No errors in the console"
5. What I already tried:         "I checked the Network tab — the API returns 200 with data"
6. Relevant code:                [minimal code snippet]
```

A question like this gets answered quickly. "My code doesn't work, help" does not.

<Info>
  Creating a minimal reproduction is the most valuable debugging skill you can develop. Often, the act of simplifying the problem to its essentials reveals the bug — and you solve it yourself before even asking.
</Info>

## Reference documentation

Bookmark these. You'll come back to them constantly.

| Resource                               | What it covers                                      |
| -------------------------------------- | --------------------------------------------------- |
| **MDN Web Docs**                       | JavaScript, DOM, Web APIs, CSS                      |
| **react.dev**                          | React components, hooks, patterns                   |
| **fastapi.tiangolo.com**               | FastAPI endpoints, validation, middleware           |
| **vitejs.dev**                         | Vite configuration, environment variables, building |
| **developer.chrome.com/docs/devtools** | Chrome DevTools guides                              |

## Common problems and where to look

| Problem                               | Where to check                                                |
| ------------------------------------- | ------------------------------------------------------------- |
| "Cannot read properties of undefined" | Your data isn't what you think — `console.log` it             |
| CORS error in console                 | Backend CORS middleware configuration                         |
| API returns 422                       | Your request body doesn't match the Pydantic model            |
| Component doesn't re-render           | You might be mutating state instead of creating new objects   |
| useEffect runs infinitely             | Check your dependency array for objects/arrays                |
| Form input won't type                 | Missing `onChange` handler on a controlled input              |
| "Module not found"                    | Check your import path — relative (`./`) and case sensitivity |
| `key` warning in console              | Add a unique `key` prop to items in `.map()`                  |

## Contributing to this course

Found a typo? Want to suggest an improvement? This course is open source.

* **Report issues**: Open a GitHub issue describing the problem
* **Suggest improvements**: Pull requests are welcome
* **Share feedback**: Let us know what helped and what was confusing

## Keep going

You've completed the course. You have the foundation. The rest is practice and curiosity.

Build something this week. It doesn't have to be perfect — it has to exist. Every project you build makes you better. Every bug you fix teaches you something new.

Welcome to full-stack development.


# Recommended resources
Source: https://js.maxbraglia.com/next-steps/recommended-resources

Continue learning with these curated resources for JavaScript and React

## Official documentation

These are the definitive references. When you need to look something up, go here first.

### JavaScript

**MDN Web Docs** — The single best JavaScript reference. Written by Mozilla, used by everyone.

* JavaScript Guide: `developer.mozilla.org/en-US/docs/Web/JavaScript/Guide`
* Array methods: `developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array`
* Fetch API: `developer.mozilla.org/en-US/docs/Web/API/Fetch_API`

<Tip>
  When you Google a JavaScript question, add "MDN" to your search. The MDN result is almost always the most accurate and well-explained answer. Example: "array map MDN".
</Tip>

### React

**React docs** — Completely rewritten in 2023 with interactive examples and modern patterns.

* Quick Start: `react.dev/learn`
* Hooks reference: `react.dev/reference/react`
* Thinking in React: `react.dev/learn/thinking-in-react`

### FastAPI

**FastAPI docs** — Excellent documentation with a tutorial-first approach.

* Tutorial: `fastapi.tiangolo.com/tutorial`
* Deployment: `fastapi.tiangolo.com/deployment`

## What to learn next

You've learned the essentials. Here's what to add to your toolkit, in order of usefulness:

### 1. TypeScript

TypeScript adds types to JavaScript. It catches bugs before your code runs — especially data shape mismatches between frontend and backend.

* **Why**: Catch `undefined` errors, get autocomplete, document your code automatically
* **When**: Once you're comfortable with JavaScript (after 1-2 projects)
* **Where to start**: `typescriptlang.org/docs/handbook`

```tsx theme={null}
// TypeScript catches this at development time
interface User {
  id: number;
  name: string;
  email: string;
}

function greet(user: User) {
  return `Hello, ${user.username}`; // ❌ Error: 'username' doesn't exist on type 'User'
}
```

### 2. React Router

Add multiple pages to your React app. Right now you have one page — React Router gives you `/users`, `/users/3`, `/settings`, etc.

* **Why**: Every real app needs multiple pages/routes
* **When**: Your next project
* **Where to start**: `reactrouter.com/start/framework/installation`

### 3. TanStack Query (React Query)

Replaces your manual `useState` + `useEffect` + loading/error pattern for data fetching with a single hook.

* **Why**: Automatic caching, background refetching, loading/error states handled for you
* **When**: When you're tired of writing the loading/error/data pattern manually
* **Where to start**: `tanstack.com/query`

```jsx theme={null}
// Instead of useState + useEffect + loading + error...
const { data: users, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: getUsers,
});
```

### 4. Tailwind CSS

Utility-first CSS framework. Instead of writing CSS files, you add classes directly to your JSX.

* **Why**: Build UIs faster without switching between CSS and JSX files
* **When**: Anytime — it's just CSS
* **Where to start**: `tailwindcss.com/docs`

```jsx theme={null}
// No CSS files needed
<button className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600">
  Click me
</button>
```

### 5. Testing

Learn to test your components and API calls. Start with Vitest (test runner) and React Testing Library.

* **Why**: Confidence that your code works, catch regressions
* **When**: Once you have a project worth maintaining
* **Where to start**: `vitest.dev` and `testing-library.com/docs/react-testing-library`

## Practice platforms

Build things. Reading tutorials only gets you 20% of the way — building gets you the other 80%.

| Platform                    | What it's good for                            |
| --------------------------- | --------------------------------------------- |
| **Build your own projects** | Best way to learn — pick an idea and build it |
| **Frontend Mentor**         | Real-world design challenges to build         |
| **JavaScript30**            | 30 small vanilla JS projects by Wes Bos       |
| **freeCodeCamp**            | Structured JavaScript curriculum (free)       |
| **Exercism**                | JavaScript exercises with mentoring           |

<Tip>
  The best project to build is one you'll actually use. A personal budget tracker, a recipe organizer, a reading list app — something you care about. Motivation matters more than complexity.
</Tip>

## Project ideas

Start small, then grow:

1. **Todo app** — The classic. CRUD with localStorage, then upgrade to a FastAPI backend.
2. **Weather dashboard** — Fetch from a public API, display with React.
3. **Personal bookmarks** — Save links with tags, search and filter them.
4. **Expense tracker** — Forms, calculations, charts. Full-stack with FastAPI.
5. **Blog platform** — Markdown posts, categories, admin panel.

Each project reinforces different skills from this course. Pick one and build it this week.

<Card title="Deployment basics" icon="rocket" href="/next-steps/deployment-basics">
  Get your full-stack application live on the internet
</Card>


# The essential 20 percent
Source: https://js.maxbraglia.com/next-steps/the-essential-20-percent

A quick reference of the JavaScript concepts you'll use 80% of the time

## Your cheat sheet

This is the 20% of JavaScript you'll use 80% of the time. Bookmark this page. Come back to it when you forget a syntax. Everything here was covered in the course — this is just the concentrated version.

## Variables

```jsx theme={null}
const name = "Sarah Chen";   // Can't reassign — use for most things
let count = 0;                // Can reassign — use for values that change
// Forget var exists
```

## Template literals

```jsx theme={null}
const greeting = `Hello, ${name}! You have ${count} items.`;

// Multi-line
const html = `
  <div>
    <h1>${title}</h1>
    <p>${description}</p>
  </div>
`;
```

## Functions

```jsx theme={null}
// Arrow function (use this 90% of the time)
const add = (a, b) => a + b;

// Arrow with body
const greet = (name) => {
  const message = `Hello, ${name}!`;
  return message;
};

// Default parameters
const createUser = (name, role = "viewer") => ({ name, role });

// Destructuring parameters
const renderUser = ({ name, email }) => `${name} (${email})`;
```

## Arrays

```jsx theme={null}
const users = ["Sarah", "John", "Maria"];

// The essential methods
users.map(u => u.toUpperCase())      // Transform: ["SARAH", "JOHN", "MARIA"]
users.filter(u => u !== "John")      // Filter:    ["Sarah", "Maria"]
users.find(u => u === "Sarah")       // Find one:  "Sarah"
users.includes("Maria")             // Check:     true
users.forEach(u => console.log(u))   // Loop (no return value)

// Spread
const withNew = [...users, "Alex"];  // ["Sarah", "John", "Maria", "Alex"]
```

## Objects

```jsx theme={null}
const user = { name: "Sarah Chen", email: "sarah@example.com", role: "admin" };

// Access
user.name                     // "Sarah Chen"
user["name"]                  // "Sarah Chen" (dynamic access)

// Destructuring
const { name, email } = user; // name = "Sarah Chen", email = "sarah@example.com"

// Spread (copy + override)
const updated = { ...user, role: "viewer" };
```

## Conditionals

```jsx theme={null}
// Ternary — choose between two values
const label = isActive ? "Active" : "Inactive";

// && — show or nothing
const badge = isAdmin && <span>Admin</span>;

// Nullish coalescing — default for null/undefined
const displayName = user.nickname ?? "Anonymous";
```

## Async / await

```jsx theme={null}
async function fetchUsers() {
  try {
    const response = await fetch("/api/users");
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    return data;
  } catch (err) {
    console.error("Failed:", err.message);
    throw err;
  }
}
```

## Fetch — all HTTP methods

```jsx theme={null}
// GET
const response = await fetch("/api/users");
const users = await response.json();

// POST
const response = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Sarah", email: "sarah@example.com" }),
});

// PUT
await fetch(`/api/users/${id}`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(updatedData),
});

// DELETE
await fetch(`/api/users/${id}`, { method: "DELETE" });
```

## React — components and JSX

```jsx theme={null}
// Component = function that returns JSX
function UserCard({ name, email, isAdmin }) {
  return (
    <div className="card">
      <h2>{name}</h2>
      <p>{email}</p>
      {isAdmin && <span className="badge">Admin</span>}
    </div>
  );
}

// Use it
<UserCard name="Sarah Chen" email="sarah@example.com" isAdmin={true} />
```

## React — state

```jsx theme={null}
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(prev => prev + 1)}>
      Clicked {count} times
    </button>
  );
}
```

## React — effects (data fetching)

```jsx theme={null}
import { useState, useEffect } from 'react';

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetch("/api/users")
      .then(r => r.json())
      .then(data => setUsers(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, []); // Empty array = run once on mount

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

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

## React — controlled forms

```jsx theme={null}
function CreateForm({ onSubmit }) {
  const [formData, setFormData] = useState({ name: "", email: "" });

  function handleChange(e) {
    setFormData(prev => ({ ...prev, [e.target.name]: e.target.value }));
  }

  function handleSubmit(e) {
    e.preventDefault();
    onSubmit(formData);
    setFormData({ name: "", email: "" });
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={formData.name} onChange={handleChange} />
      <input name="email" value={formData.email} onChange={handleChange} />
      <button type="submit">Create</button>
    </form>
  );
}
```

## React — CRUD state updates

```jsx theme={null}
// CREATE
setUsers(prev => [...prev, newUser]);

// UPDATE
setUsers(prev => prev.map(u => u.id === updated.id ? updated : u));

// DELETE
setUsers(prev => prev.filter(u => u.id !== userId));
```

## Import / export

```jsx theme={null}
// Named exports (multiple per file)
export function getUsers() { ... }
export function createUser(data) { ... }
import { getUsers, createUser } from './api/users';

// Default export (one per file)
export default function UserCard() { ... }
import UserCard from './components/UserCard';
```

That's the 20%. Everything else you need, you can look up when you need it.

<Card title="Recommended resources" icon="book" href="/next-steps/recommended-resources">
  Continue learning with curated resources for JavaScript and React
</Card>


# Component composition
Source: https://js.maxbraglia.com/react-essentials/component-composition

Structure your React app with smart and presentational components

## Two kinds of components

As your app grows, you'll naturally split components into two roles:

|                    | Smart components              | Presentational components               |
| ------------------ | ----------------------------- | --------------------------------------- |
| **Also called**    | Container, page, parent       | Display, UI, child                      |
| **Manages state?** | Yes — `useState`, `useEffect` | No — receives data via props            |
| **Fetches data?**  | Yes                           | No                                      |
| **Handles logic?** | Business logic, API calls     | Display logic only (formatting, layout) |
| **Reusable?**      | Usually not                   | Highly reusable                         |

```jsx theme={null}
// Smart component — owns state, fetches data, passes it down
function UserDashboard() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch("/api/users")
      .then(r => r.json())
      .then(data => setUsers(data))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <Spinner />;

  return (
    <div>
      <h1>Users</h1>
      <UserList users={users} />
    </div>
  );
}

// Presentational component — just renders what it receives
function UserList({ users }) {
  return (
    <ul>
      {users.map(user => (
        <UserCard key={user.id} name={user.name} email={user.email} />
      ))}
    </ul>
  );
}

function UserCard({ name, email }) {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
}
```

`UserDashboard` knows about APIs and state. `UserList` and `UserCard` know nothing about where data comes from — they just display what they receive. This separation makes presentational components reusable across your app.

<Tip>
  You don't need to force every component into one category. This is a guideline, not a rule. The goal is simple: push state management up and keep display components focused on rendering.
</Tip>

## Lifting state up

When two sibling components need the same data, move the state to their shared parent:

```jsx theme={null}
// ❌ Problem: SearchBar and UserList both need the search term,
// but they're siblings — they can't share state directly

// ✅ Solution: Lift state up to the parent
function UserPage() {
  const [users, setUsers] = useState([]);
  const [search, setSearch] = useState(""); // State lives here

  useEffect(() => {
    fetch("/api/users")
      .then(r => r.json())
      .then(data => setUsers(data));
  }, []);

  const filtered = users.filter(user =>
    user.name.toLowerCase().includes(search.toLowerCase())
  );

  return (
    <div>
      <SearchBar search={search} onSearchChange={setSearch} />
      <UserList users={filtered} />
    </div>
  );
}

function SearchBar({ search, onSearchChange }) {
  return (
    <input
      type="text"
      value={search}
      onChange={e => onSearchChange(e.target.value)}
      placeholder="Search users..."
    />
  );
}

function UserList({ users }) {
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name} — {user.email}</li>
      ))}
    </ul>
  );
}
```

`UserPage` owns the state. `SearchBar` updates it via a callback. `UserList` reads the filtered result. Neither child knows about the other — the parent coordinates everything.

<Info>
  "Lifting state up" is the answer to "how do sibling components share data?" Move the state to the nearest common parent. The parent passes data down via props and receives updates via callback props.
</Info>

## Callback props — child-to-parent communication

Props flow **down** (parent → child). For the reverse direction, pass a function as a prop:

```jsx theme={null}
function TodoApp() {
  const [todos, setTodos] = useState([]);

  function handleAddTodo(text) {
    setTodos(prev => [...prev, { id: Date.now(), text, done: false }]);
  }

  function handleToggleTodo(id) {
    setTodos(prev =>
      prev.map(todo =>
        todo.id === id ? { ...todo, done: !todo.done } : todo
      )
    );
  }

  function handleDeleteTodo(id) {
    setTodos(prev => prev.filter(todo => todo.id !== id));
  }

  return (
    <div>
      <h1>Todos ({todos.length})</h1>
      <AddTodoForm onAdd={handleAddTodo} />
      <TodoList
        todos={todos}
        onToggle={handleToggleTodo}
        onDelete={handleDeleteTodo}
      />
    </div>
  );
}

function AddTodoForm({ onAdd }) {
  const [text, setText] = useState("");

  function handleSubmit(e) {
    e.preventDefault();
    if (!text.trim()) return;
    onAdd(text);     // Call the parent's function
    setText("");      // Clear the input
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
        placeholder="Add a todo..."
      />
      <button type="submit">Add</button>
    </form>
  );
}

function TodoList({ todos, onToggle, onDelete }) {
  return (
    <ul>
      {todos.map(todo => (
        <TodoItem
          key={todo.id}
          todo={todo}
          onToggle={onToggle}
          onDelete={onDelete}
        />
      ))}
    </ul>
  );
}

function TodoItem({ todo, onToggle, onDelete }) {
  return (
    <li>
      <span
        style={{ textDecoration: todo.done ? "line-through" : "none" }}
        onClick={() => onToggle(todo.id)}
      >
        {todo.text}
      </span>
      <button onClick={() => onDelete(todo.id)}>Delete</button>
    </li>
  );
}
```

The data flow is clear: `TodoApp` owns all the state and logic. Children communicate back by calling the callback props (`onAdd`, `onToggle`, `onDelete`). No child modifies state directly.

## A full composition example

Here's a realistic page that combines everything — fetch, state, forms, lists, and composition:

```jsx theme={null}
import { useState, useEffect } from 'react';

// Smart component — owns all the state
function DashboardPage() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUsers() {
      try {
        const response = await fetch("/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        setUsers(await response.json());
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []);

  async function handleCreateUser(userData) {
    const response = await fetch("/api/users", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(userData),
    });
    const newUser = await response.json();
    setUsers(prev => [...prev, newUser]);
  }

  async function handleDeleteUser(userId) {
    await fetch(`/api/users/${userId}`, { method: "DELETE" });
    setUsers(prev => prev.filter(u => u.id !== userId));
  }

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

  return (
    <div>
      <h1>User Dashboard</h1>
      <CreateUserForm onSubmit={handleCreateUser} />
      <UserTable users={users} onDelete={handleDeleteUser} />
    </div>
  );
}

// Presentational — form with its own local state
function CreateUserForm({ onSubmit }) {
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");

  function handleSubmit(e) {
    e.preventDefault();
    onSubmit({ name, email });
    setName("");
    setEmail("");
  }

  return (
    <form onSubmit={handleSubmit}>
      <input value={name} onChange={e => setName(e.target.value)} placeholder="Name" />
      <input value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" />
      <button type="submit">Add User</button>
    </form>
  );
}

// Presentational — just renders the list
function UserTable({ users, onDelete }) {
  if (users.length === 0) return <p>No users yet.</p>;

  return (
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Email</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {users.map(user => (
          <tr key={user.id}>
            <td>{user.name}</td>
            <td>{user.email}</td>
            <td>
              <button onClick={() => onDelete(user.id)}>Delete</button>
            </td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

Notice the pattern: `DashboardPage` handles all API calls and state. `CreateUserForm` has local state for the input fields, but the actual "create" logic lives in the parent. `UserTable` is pure display.

## Rules of thumb

1. **State goes in the highest component that needs it** — not higher, not lower
2. **If two components need the same data** — lift the state to their parent
3. **Smart components fetch and manage** — presentational components display
4. **Callback props for child → parent** — never modify parent state directly from a child
5. **Local state is fine for UI-only state** — form inputs, open/closed toggles, hover states

<Tip>
  Don't try to make every component "dumb." Form components naturally need local state for their inputs. The goal isn't zero state in children — it's putting *shared* state in the right place and keeping *API logic* in smart components.
</Tip>

## What's next?

You've learned the React essentials — components, props, state, effects, conditional rendering, lists, forms, and composition. These 8 concepts cover 90% of what you'll do in React.

Now let's put it all together. In the next section, you'll connect your React frontend to a FastAPI backend and build a complete full-stack application.

<Card title="Full-stack project structure" icon="folder-tree" href="/full-stack/project-structure">
  Organize a project with a React frontend and FastAPI backend
</Card>


# Components and JSX
Source: https://js.maxbraglia.com/react-essentials/components-jsx

Build UI with reusable components using JSX syntax

## Components are functions

A React component is a JavaScript function that returns JSX — a description of what should appear on screen.

```jsx theme={null}
function Greeting() {
  return <h1>Hello, World!</h1>;
}
```

That's a complete React component. A function. Returns JSX. Done.

### Rules for components

1. **Name starts with a capital letter** — `UserCard`, not `userCard`
2. **Returns JSX** — the UI description
3. **One component per file** (convention, not required)
4. **Export it** so other files can use it

```jsx theme={null}
// src/UserCard.jsx
function UserCard() {
  return (
    <div className="user-card">
      <h2>Sarah Chen</h2>
      <p>sarah@example.com</p>
    </div>
  );
}

export default UserCard;
```

```jsx theme={null}
// src/App.jsx
import UserCard from './UserCard';

function App() {
  return (
    <div>
      <UserCard />
      <UserCard />
    </div>
  );
}
```

<Warning>
  Component names must start with a capital letter. `<UserCard />` renders your component. `<userCard />` is treated as an HTML tag (which doesn't exist) and silently fails.
</Warning>

## What is JSX?

JSX is a syntax extension that lets you write HTML-like code inside JavaScript. It's not actual HTML — it gets compiled to JavaScript function calls.

```jsx theme={null}
// What you write (JSX)
const element = <h1 className="title">Hello</h1>;

// What the browser sees (JavaScript)
const element = React.createElement('h1', { className: 'title' }, 'Hello');
```

You never write the `React.createElement` version. JSX does it for you. But knowing it's just JavaScript under the hood helps explain the rules.

## JSX rules

### 1. Return a single root element

```jsx theme={null}
// ❌ Error: Adjacent JSX elements must be wrapped
function UserCard() {
  return (
    <h2>Sarah Chen</h2>
    <p>sarah@example.com</p>
  );
}

// ✅ Wrap in a parent element
function UserCard() {
  return (
    <div>
      <h2>Sarah Chen</h2>
      <p>sarah@example.com</p>
    </div>
  );
}

// ✅ Or use a Fragment (no extra DOM element)
function UserCard() {
  return (
    <>
      <h2>Sarah Chen</h2>
      <p>sarah@example.com</p>
    </>
  );
}
```

`<>...</>` is a **Fragment** — it groups elements without adding an extra DOM node. Use it when you don't need a wrapper `div`.

### 2. className instead of class

```jsx theme={null}
// ❌ Wrong — class is a reserved word in JavaScript
<div class="card">

// ✅ Correct
<div className="card">
```

### 3. camelCase for attributes

```jsx theme={null}
// HTML            →  JSX
// onclick         →  onClick
// onchange        →  onChange
// tabindex        →  tabIndex
// for             →  htmlFor
// style=""        →  style={{}}

<button onClick={handleClick}>Click me</button>
<label htmlFor="email">Email</label>
<div tabIndex={0}>Focusable</div>
```

### 4. Close all tags

```jsx theme={null}
// HTML allows self-closing tags to be open
// <img src="photo.jpg">
// <br>
// <input type="text">

// JSX requires all tags to be closed
<img src="photo.jpg" />
<br />
<input type="text" />
```

### 5. JavaScript expressions in curly braces

Use `{}` to embed any JavaScript expression inside JSX:

```jsx theme={null}
function UserCard({ user }) {
  const fullName = `${user.firstName} ${user.lastName}`;

  return (
    <div className="user-card">
      <h2>{fullName}</h2>
      <p>{user.email}</p>
      <p>Joined: {new Date(user.createdAt).toLocaleDateString()}</p>
      <p>Posts: {user.posts.length}</p>
      <span className={user.isActive ? "active" : "inactive"}>
        {user.isActive ? "Active" : "Inactive"}
      </span>
    </div>
  );
}
```

Inside `{}` you can use:

* Variables: `{name}`
* Expressions: `{count + 1}`
* Function calls: `{formatDate(date)}`
* Ternary operators: `{isActive ? "Yes" : "No"}`
* Template literals: ``{`Hello, ${name}`}``

<Warning>
  You can only use **expressions** inside `{}`, not statements. `{if (x) ...}` won't work. Use ternary operators or `&&` instead. `{x ? "yes" : "no"}` and `{x && "shown"}` are the React way.
</Warning>

## Inline styles

JSX styles use a JavaScript object with camelCase properties:

```jsx theme={null}
// HTML:  <div style="background-color: blue; font-size: 16px;">
// JSX:
<div style={{ backgroundColor: "blue", fontSize: "16px" }}>
  Styled content
</div>
```

The double braces `{{ }}` are: outer `{}` for "this is JavaScript", inner `{}` for "this is an object."

```jsx theme={null}
// You can also define styles separately
const cardStyle = {
  padding: "16px",
  borderRadius: "8px",
  backgroundColor: "#f9fafb",
  boxShadow: "0 1px 3px rgba(0,0,0,0.1)",
};

function Card({ children }) {
  return <div style={cardStyle}>{children}</div>;
}
```

<Tip>
  Inline styles work but aren't ideal for large apps. For most projects, use CSS files (`import './App.css'`), CSS modules, or a library like Tailwind CSS. Inline styles are fine for dynamic values like `width: ${percentage}%`.
</Tip>

## JSX vs HTML cheat sheet

| HTML                 | JSX                        |
| -------------------- | -------------------------- |
| `class="card"`       | `className="card"`         |
| `for="email"`        | `htmlFor="email"`          |
| `onclick="fn()"`     | `onClick={fn}`             |
| `style="color: red"` | `style={{ color: "red" }}` |
| `<br>`               | `<br />`                   |
| `<img src="...">`    | `<img src="..." />`        |
| `tabindex="0"`       | `tabIndex={0}`             |
| `<!-- comment -->`   | `{/* comment */}`          |

## Common mistakes

<AccordionGroup>
  <Accordion title="Returning multiple elements without a wrapper">
    ```jsx theme={null}
    // ❌ Error
    function Card() {
      return (
        <h2>Title</h2>
        <p>Content</p>
      );
    }

    // ✅ Use a Fragment
    function Card() {
      return (
        <>
          <h2>Title</h2>
          <p>Content</p>
        </>
      );
    }
    ```

    <Warning>
      A component must return a single root element. Use `<>...</>` (Fragment) when you don't need an actual wrapper div in the DOM.
    </Warning>
  </Accordion>

  <Accordion title="Using class instead of className">
    ```jsx theme={null}
    // ❌ Warning in console
    <div class="card">Content</div>

    // ✅ Correct
    <div className="card">Content</div>
    ```

    This is the most common JSX mistake. React will show a warning in the console, but it's easy to miss.
  </Accordion>

  <Accordion title="Forgetting curly braces for JavaScript">
    ```jsx theme={null}
    const name = "Sarah";

    // ❌ Literal text "name"
    <h1>name</h1>

    // ✅ JavaScript variable
    <h1>{name}</h1>
    ```
  </Accordion>
</AccordionGroup>

## What's next?

Components are reusable, but right now they always show the same content. Let's make them dynamic by passing data in with props.

<Card title="Props" icon="arrow-right" href="/react-essentials/props">
  Pass data between React components
</Card>


# Conditional rendering
Source: https://js.maxbraglia.com/react-essentials/conditional-rendering

Show different UI based on state and conditions

## Showing the right thing at the right time

React apps constantly need to show different UI based on conditions: a spinner while loading, an error message if something failed, a login button if the user isn't authenticated. This is conditional rendering.

You already know the JavaScript for this — ternary operators, `&&`, and if/else from the conditionals lesson. In React, you use the same patterns inside JSX.

## && — show something or nothing

The most common pattern. Show an element if a condition is true, nothing if false:

```jsx theme={null}
function UserCard({ user }) {
  return (
    <div className="user-card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      {user.isAdmin && <span className="badge">Admin</span>}
      {user.bio && <p className="bio">{user.bio}</p>}
    </div>
  );
}
```

`&&` is perfect when you want to either show something or show nothing. If the left side is truthy, the right side renders. If falsy, nothing renders.

<Warning>
  Watch out for `0 && <Component />`. Because `0` is falsy, React renders the number `0` on the page instead of nothing. Use `count > 0 && <Component />` instead of `count && <Component />`.
</Warning>

## Ternary — show one thing or another

When you need to choose between two different outputs:

```jsx theme={null}
function UserGreeting({ user }) {
  return (
    <div>
      {user ? (
        <h1>Welcome back, {user.name}!</h1>
      ) : (
        <h1>Please log in</h1>
      )}
    </div>
  );
}
```

```jsx theme={null}
// Inline ternary for simple cases
<button className={isActive ? "btn-primary" : "btn-secondary"}>
  {isActive ? "Active" : "Inactive"}
</button>

// Conditional styles
<div style={{ color: error ? "red" : "green" }}>
  {error ? error : "All good!"}
</div>
```

<Tip>
  Use `&&` when you have a show/hide situation. Use ternary when you have an either/or situation. Keep ternaries simple — if the logic gets complex, extract it to a variable or use early returns.
</Tip>

## Early returns — the cleanest pattern

For loading, error, and empty states, use early returns at the top of your component:

```jsx theme={null}
function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // ... useEffect to fetch data ...

  // Early returns — check each state
  if (loading) return <Spinner />;
  if (error) return <ErrorMessage message={error} />;
  if (users.length === 0) return <p>No users found.</p>;

  // Main render — only reached when we have data
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

This is the standard pattern for data-fetching components. Check states in order of priority: loading → error → empty → data.

## The loading / error / data pattern

You'll write this in almost every component that fetches data:

```jsx theme={null}
function ProductPage({ productId }) {
  const [product, setProduct] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadProduct() {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch(`/api/products/${productId}`);
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        setProduct(await response.json());
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadProduct();
  }, [productId]);

  if (loading) return <p>Loading product...</p>;
  if (error) return <p>Error: {error}</p>;
  if (!product) return <p>Product not found</p>;

  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <p>{product.description}</p>
      {product.inStock ? (
        <button>Add to Cart</button>
      ) : (
        <p className="out-of-stock">Out of Stock</p>
      )}
    </div>
  );
}
```

## Conditional CSS classes

```jsx theme={null}
// Toggle a class
<div className={`card ${isSelected ? "selected" : ""}`}>

// Multiple conditional classes
<button className={[
  "btn",
  variant === "primary" ? "btn-primary" : "btn-secondary",
  size === "lg" ? "btn-lg" : "",
  disabled ? "btn-disabled" : "",
].filter(Boolean).join(" ")}>
  {label}
</button>
```

<Tip>
  For complex class logic, consider a utility like `clsx` or `classnames`: `className={clsx("btn", isPrimary && "btn-primary", isLarge && "btn-lg")}`. It's cleaner than manual string concatenation.
</Tip>

## Conditional rendering with variables

For more complex conditions, compute the JSX before the return:

```jsx theme={null}
function StatusBadge({ status }) {
  let badge;

  if (status === "active") {
    badge = <span className="badge green">Active</span>;
  } else if (status === "pending") {
    badge = <span className="badge yellow">Pending</span>;
  } else if (status === "inactive") {
    badge = <span className="badge red">Inactive</span>;
  } else {
    badge = <span className="badge gray">Unknown</span>;
  }

  return <div className="status">{badge}</div>;
}
```

Or with an object lookup (cleaner for many cases):

```jsx theme={null}
function StatusBadge({ status }) {
  const badges = {
    active: { className: "green", label: "Active" },
    pending: { className: "yellow", label: "Pending" },
    inactive: { className: "red", label: "Inactive" },
  };

  const badge = badges[status] || { className: "gray", label: "Unknown" };

  return (
    <span className={`badge ${badge.className}`}>
      {badge.label}
    </span>
  );
}
```

## Preventing rendering with null

Return `null` to render nothing:

```jsx theme={null}
function Notification({ message }) {
  if (!message) return null; // Don't render at all

  return <div className="notification">{message}</div>;
}
```

## What's next?

You can show and hide UI based on conditions. Now let's learn how to render lists of data — the most common thing you'll do with API responses.

<Card title="List rendering" icon="list" href="/react-essentials/list-rendering">
  Render arrays of data as lists of components
</Card>


# Forms in React
Source: https://js.maxbraglia.com/react-essentials/forms-in-react

Build controlled forms that sync input values with React state

## Controlled components

In vanilla JavaScript, form inputs manage their own values. In React, you'll often manage input values with state. This is called a controlled component — React state is the single source of truth.

```jsx theme={null}
import { useState } from 'react';

function SearchBar() {
  const [query, setQuery] = useState("");

  return (
    <input
      type="text"
      value={query}
      onChange={e => setQuery(e.target.value)}
      placeholder="Search..."
    />
  );
}
```

Two things make an input "controlled":

1. **`value`** — set from state (React controls what's displayed)
2. **`onChange`** — updates state when the user types

Without both, the input either won't display the right value or won't respond to typing.

<Warning>
  If you set `value` without `onChange`, the input becomes read-only — the user can't type in it. React will warn you about this in the console. Always pair `value` with `onChange`.
</Warning>

## All input types

The `value` + `onChange` pattern works the same way for most common input types:

```jsx theme={null}
function AllInputTypes() {
  const [name, setName] = useState("");
  const [age, setAge] = useState("");
  const [bio, setBio] = useState("");
  const [agreed, setAgreed] = useState(false);
  const [role, setRole] = useState("viewer");
  const [plan, setPlan] = useState("free");

  return (
    <form>
      {/* Text input */}
      <input
        type="text"
        value={name}
        onChange={e => setName(e.target.value)}
      />

      {/* Number input */}
      <input
        type="number"
        value={age}
        onChange={e => setAge(e.target.value)}
      />

      {/* Textarea */}
      <textarea
        value={bio}
        onChange={e => setBio(e.target.value)}
      />

      {/* Checkbox — uses checked, not value */}
      <label>
        <input
          type="checkbox"
          checked={agreed}
          onChange={e => setAgreed(e.target.checked)}
        />
        I agree to the terms
      </label>

      {/* Select dropdown */}
      <select value={role} onChange={e => setRole(e.target.value)}>
        <option value="viewer">Viewer</option>
        <option value="editor">Editor</option>
        <option value="admin">Admin</option>
      </select>

      {/* Radio buttons — same state, different values */}
      <label>
        <input
          type="radio"
          name="plan"
          value="free"
          checked={plan === "free"}
          onChange={e => setPlan(e.target.value)}
        />
        Free
      </label>
      <label>
        <input
          type="radio"
          name="plan"
          value="pro"
          checked={plan === "pro"}
          onChange={e => setPlan(e.target.value)}
        />
        Pro
      </label>
    </form>
  );
}
```

<Info>
  Checkboxes use `checked` and `e.target.checked`. Most other inputs use `value` and `e.target.value`. (File inputs are a special case and are usually handled as uncontrolled inputs.)
</Info>

<Tip>
  Even for `<input type="number">`, `e.target.value` is still a **string**. Convert it with `Number(...)` (or `parseInt`/`parseFloat`) when you actually need a number.
</Tip>

## Handling form submission

Use `onSubmit` on the `<form>` element, not `onClick` on the button:

```jsx theme={null}
function CreateUserForm() {
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [submitting, setSubmitting] = useState(false);

  async function handleSubmit(e) {
    e.preventDefault(); // Stop the page from reloading

    setSubmitting(true);
    try {
      const response = await fetch("/api/users", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name, email }),
      });

      if (!response.ok) throw new Error(`HTTP ${response.status}`);

      const newUser = await response.json();
      console.log("Created:", newUser);

      // Clear the form
      setName("");
      setEmail("");
    } catch (err) {
      console.error("Failed to create user:", err);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={name}
        onChange={e => setName(e.target.value)}
        placeholder="Name"
        required
      />
      <input
        type="email"
        value={email}
        onChange={e => setEmail(e.target.value)}
        placeholder="Email"
        required
      />
      <button type="submit" disabled={submitting}>
        {submitting ? "Creating..." : "Create User"}
      </button>
    </form>
  );
}
```

<Tip>
  Always use `e.preventDefault()` in your submit handler. Without it, the browser reloads the page (the default HTML form behavior), which destroys your React app state. Use `onSubmit` on the form, not `onClick` on the button — this way pressing Enter also submits.
</Tip>

## Managing multiple fields with one state object

When forms have many fields, use a single state object instead of separate `useState` calls:

```jsx theme={null}
function RegistrationForm() {
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    password: "",
    role: "viewer",
  });

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({
      ...prev,
      [name]: value,
    }));
  }

  function handleSubmit(e) {
    e.preventDefault();
    console.log("Submitting:", formData);
    // POST to API...
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="name"
        type="text"
        value={formData.name}
        onChange={handleChange}
        placeholder="Name"
      />
      <input
        name="email"
        type="email"
        value={formData.email}
        onChange={handleChange}
        placeholder="Email"
      />
      <input
        name="password"
        type="password"
        value={formData.password}
        onChange={handleChange}
        placeholder="Password"
      />
      <select name="role" value={formData.role} onChange={handleChange}>
        <option value="viewer">Viewer</option>
        <option value="editor">Editor</option>
        <option value="admin">Admin</option>
      </select>
      <button type="submit">Register</button>
    </form>
  );
}
```

The key trick is `[name]: value` — a computed property name. The input's `name` attribute matches the key in state, so one `handleChange` function works for all fields.

<Info>
  Every input needs a `name` attribute that matches the state key. `handleChange` reads `e.target.name` to know which field to update. This is the standard pattern for multi-field forms in React.
</Info>

## Basic validation

Show errors per field and validate on submit:

```jsx theme={null}
function LoginForm() {
  const [formData, setFormData] = useState({ email: "", password: "" });
  const [errors, setErrors] = useState({});

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));

    // Clear error when user starts typing
    if (errors[name]) {
      setErrors(prev => ({ ...prev, [name]: null }));
    }
  }

  function validate() {
    const newErrors = {};

    if (!formData.email) {
      newErrors.email = "Email is required";
    } else if (!formData.email.includes("@")) {
      newErrors.email = "Invalid email address";
    }

    if (!formData.password) {
      newErrors.password = "Password is required";
    } else if (formData.password.length < 8) {
      newErrors.password = "Password must be at least 8 characters";
    }

    return newErrors;
  }

  function handleSubmit(e) {
    e.preventDefault();

    const newErrors = validate();
    if (Object.keys(newErrors).length > 0) {
      setErrors(newErrors);
      return; // Don't submit
    }

    console.log("Valid! Submitting:", formData);
    // POST to API...
  }

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <input
          name="email"
          type="email"
          value={formData.email}
          onChange={handleChange}
          placeholder="Email"
        />
        {errors.email && <p className="error">{errors.email}</p>}
      </div>

      <div>
        <input
          name="password"
          type="password"
          value={formData.password}
          onChange={handleChange}
          placeholder="Password"
        />
        {errors.password && <p className="error">{errors.password}</p>}
      </div>

      <button type="submit">Log In</button>
    </form>
  );
}
```

The pattern: validate on submit, show errors with `&&`, clear errors when the user starts fixing them.

<Tip>
  For production apps, consider a form library like React Hook Form. But this manual pattern teaches you exactly what's happening and works well for simple forms. Understand this pattern first, then add libraries when you need them.
</Tip>

## Edit forms — pre-populated from data

Edit forms start with existing data passed via props:

```jsx theme={null}
function EditUserForm({ user, onSave }) {
  const [formData, setFormData] = useState({
    name: user.name,
    email: user.email,
    bio: user.bio || "",
  });

  function handleChange(e) {
    const { name, value } = e.target;
    setFormData(prev => ({ ...prev, [name]: value }));
  }

  async function handleSubmit(e) {
    e.preventDefault();

    const response = await fetch(`/api/users/${user.id}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(formData),
    });

    if (response.ok) {
      const updated = await response.json();
      onSave(updated); // Notify parent
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" value={formData.name} onChange={handleChange} />
      <input name="email" value={formData.email} onChange={handleChange} />
      <textarea name="bio" value={formData.bio} onChange={handleChange} />
      <button type="submit">Save Changes</button>
    </form>
  );
}
```

Initialize state from props for edit forms. The `onSave` callback lets the parent component know the data was updated — this is the child-to-parent communication pattern you'll learn in the next lesson.

## What's next?

You can build forms and handle user input. The last piece: how to structure your components together — which components own the data, which ones just display it, and how they communicate.

<Card title="Component composition" icon="sitemap" href="/react-essentials/component-composition">
  Structure your React app with smart and presentational components
</Card>


# List rendering
Source: https://js.maxbraglia.com/react-essentials/list-rendering

Render arrays of data as lists of components

## Arrays become lists

Most real-world React is rendering lists — users, products, messages, notifications. You already know `.map()` from the array methods lesson. In React, `.map()` turns an array of data into an array of JSX elements.

```jsx theme={null}
function UserList() {
  const users = [
    { id: 1, name: "Sarah Chen", email: "sarah@example.com" },
    { id: 2, name: "John Park", email: "john@example.com" },
    { id: 3, name: "Maria Lopez", email: "maria@example.com" },
  ];

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>
          {user.name} — {user.email}
        </li>
      ))}
    </ul>
  );
}
```

That's the entire pattern: `.map()` over an array, return JSX for each item, add a `key` prop. You'll use this in virtually every React component.

## The key prop

Every item in a list needs a unique `key` prop. React uses keys to track which items changed, were added, or were removed.

```jsx theme={null}
// ✅ Use a unique, stable identifier
{users.map(user => (
  <li key={user.id}>{user.name}</li>
))}

// ✅ Any unique string works
{emails.map(email => (
  <li key={email}>{email}</li>
))}
```

### What makes a good key?

| Key source                  | Good?       | Why                                       |
| --------------------------- | ----------- | ----------------------------------------- |
| Database ID (`user.id`)     | Best        | Unique and stable across re-renders       |
| Unique field (`user.email`) | Good        | Unique, but may change                    |
| Array index                 | Last resort | Changes when items are reordered/deleted  |
| `Math.random()`             | Never       | Different every render, breaks everything |

```jsx theme={null}
// ❌ Avoid index as key when items can be reordered or deleted
{users.map((user, index) => (
  <li key={index}>{user.name}</li>
))}

// ✅ Use the item's unique identifier
{users.map(user => (
  <li key={user.id}>{user.name}</li>
))}
```

<Warning>
  If you don't provide a `key`, React will warn you in the console. If you use array index as a key and items get reordered, React will mix up which component goes with which data — causing subtle, hard-to-debug UI bugs.
</Warning>

## Rendering components from a list

Usually you render a component for each item, not raw HTML:

```jsx theme={null}
function UserCard({ name, email, role }) {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
      <span className="badge">{role}</span>
    </div>
  );
}

function UserList({ users }) {
  return (
    <div className="user-list">
      {users.map(user => (
        <UserCard
          key={user.id}
          name={user.name}
          email={user.email}
          role={user.role}
        />
      ))}
    </div>
  );
}
```

<Info>
  The `key` goes on the outermost element in the `.map()` — which is the `<UserCard>` component, not any element inside it. React needs the key on the mapped element, not on a child within it.
</Info>

## Filtering and transforming before rendering

Process your data before the return statement. Don't try to do complex logic inside JSX:

```jsx theme={null}
function UserList({ users, searchTerm }) {
  // Filter first, then render
  const filteredUsers = users.filter(user =>
    user.name.toLowerCase().includes(searchTerm.toLowerCase())
  );

  if (filteredUsers.length === 0) {
    return <p>No users match "{searchTerm}"</p>;
  }

  return (
    <ul>
      {filteredUsers.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}
```

```jsx theme={null}
// Sort, filter, transform — all before the return
function ProductList({ products }) {
  const availableProducts = products
    .filter(p => p.inStock)
    .sort((a, b) => a.price - b.price);

  return (
    <div>
      <h2>Available Products ({availableProducts.length})</h2>
      {availableProducts.map(product => (
        <div key={product.id}>
          <span>{product.name}</span>
          <span>${product.price}</span>
        </div>
      ))}
    </div>
  );
}
```

<Tip>
  Do filtering, sorting, and transforming *above* the return statement, not inside JSX. It keeps your JSX clean and readable, and you can handle the empty state separately.
</Tip>

## A searchable list — putting it together

This combines state, effects, list rendering, and conditional rendering:

```jsx theme={null}
import { useState, useEffect } from 'react';

function SearchableUserList() {
  const [users, setUsers] = useState([]);
  const [search, setSearch] = useState("");
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUsers() {
      try {
        const response = await fetch("/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        setUsers(await response.json());
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []);

  if (loading) return <p>Loading users...</p>;
  if (error) return <p>Error: {error}</p>;

  const filtered = users.filter(user =>
    user.name.toLowerCase().includes(search.toLowerCase())
  );

  return (
    <div>
      <input
        type="text"
        placeholder="Search users..."
        value={search}
        onChange={e => setSearch(e.target.value)}
      />

      {filtered.length === 0 ? (
        <p>No users match "{search}"</p>
      ) : (
        <ul>
          {filtered.map(user => (
            <li key={user.id}>
              {user.name} — {user.email}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

This is a realistic component. Fetch data, let the user search it, render the filtered results. This pattern appears everywhere in production React apps.

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting the key prop">
    ```jsx theme={null}
    // ❌ Missing key — React warns in console
    {users.map(user => (
      <li>{user.name}</li>
    ))}

    // ✅ Always provide a key
    {users.map(user => (
      <li key={user.id}>{user.name}</li>
    ))}
    ```

    React needs keys to track which item is which across renders. Without stable keys, React can mix up item identity (especially when inserting, deleting, or reordering) and do unnecessary work.
  </Accordion>

  <Accordion title="Putting key on the wrong element">
    ```jsx theme={null}
    // ❌ Key is on <li> inside the component, not on the mapped element
    {users.map(user => (
      <UserCard user={user} />  // Missing key here!
    ))}

    function UserCard({ user }) {
      return <li key={user.id}>{user.name}</li>; // Key here does nothing
    }

    // ✅ Key goes on the element returned by .map()
    {users.map(user => (
      <UserCard key={user.id} user={user} />
    ))}
    ```
  </Accordion>

  <Accordion title="Forgetting parentheses in .map()">
    ```jsx theme={null}
    // ❌ Missing parentheses — returns undefined
    {users.map(user => {
      <li key={user.id}>{user.name}</li>
    })}

    // ✅ Use parentheses for implicit return
    {users.map(user => (
      <li key={user.id}>{user.name}</li>
    ))}

    // ✅ Or use explicit return with curly braces
    {users.map(user => {
      return <li key={user.id}>{user.name}</li>;
    })}
    ```

    <Warning>
      Arrow functions with `{}` need an explicit `return`. Arrow functions with `()` implicitly return the expression. This is a JavaScript gotcha, not a React one — but it shows up constantly in `.map()` calls.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can render lists of data. Now let's learn how to handle user input — forms are how users interact with your app.

<Card title="Forms in React" icon="input-text" href="/react-essentials/forms-in-react">
  Build controlled forms that sync input values with React state
</Card>


# Props
Source: https://js.maxbraglia.com/react-essentials/props

Pass data between React components using props

## Components need data

A `UserCard` that always shows "Sarah Chen" isn't useful. Props let you pass different data to the same component, making it reusable.

```jsx theme={null}
// Without props — hardcoded, not reusable
function UserCard() {
  return <h2>Sarah Chen</h2>;
}

// With props — dynamic, reusable
function UserCard({ name, email }) {
  return (
    <div>
      <h2>{name}</h2>
      <p>{email}</p>
    </div>
  );
}

// Use it with different data
<UserCard name="Sarah Chen" email="sarah@example.com" />
<UserCard name="John Park" email="john@example.com" />
```

Props are to React components what arguments are to functions. Same component, different data, different output.

## How props work

Props are passed as attributes in JSX and received as an object parameter:

```jsx theme={null}
// Parent passes props
<UserCard name="Sarah Chen" age={28} isAdmin={true} />

// Child receives props as an object
function UserCard(props) {
  return (
    <div>
      <h2>{props.name}</h2>
      <p>Age: {props.age}</p>
      {props.isAdmin && <span>Admin</span>}
    </div>
  );
}
```

### Destructuring props (preferred)

Instead of `props.name`, `props.age`, destructure in the parameter:

```jsx theme={null}
// ✅ Cleaner — destructure in the parameter
function UserCard({ name, age, isAdmin }) {
  return (
    <div>
      <h2>{name}</h2>
      <p>Age: {age}</p>
      {isAdmin && <span>Admin</span>}
    </div>
  );
}
```

This is the standard pattern in React. You'll see it in almost every component.

## What you can pass as props

Anything that's a valid JavaScript value:

```jsx theme={null}
// Strings
<UserCard name="Sarah Chen" />

// Numbers
<UserCard age={28} />

// Booleans
<UserCard isAdmin={true} />
<UserCard isAdmin />        {/* shorthand for isAdmin={true} */}

// Arrays
<TagList tags={["react", "javascript", "python"]} />

// Objects
<UserCard user={{ name: "Sarah", email: "sarah@example.com" }} />

// Functions
<Button onClick={() => console.log("clicked")} />

// Components
<Layout header={<Navbar />} />
```

<Info>
  Strings use quotes: `name="Sarah"`. Everything else uses curly braces: `age={28}`, `isAdmin={true}`, `items={[1,2,3]}`. This is because `{}` is how you embed JavaScript in JSX.
</Info>

## Default props

Use default parameter values for props that are optional:

```jsx theme={null}
function Button({ label = "Click me", variant = "primary", size = "md" }) {
  return (
    <button className={`btn btn-${variant} btn-${size}`}>
      {label}
    </button>
  );
}

// All props optional with defaults
<Button />                              // "Click me", primary, md
<Button label="Save" />                 // "Save", primary, md
<Button label="Delete" variant="danger" /> // "Delete", danger, md
```

## The children prop

Content between opening and closing tags becomes the `children` prop:

```jsx theme={null}
function Card({ children, title }) {
  return (
    <div className="card">
      <h3>{title}</h3>
      <div className="card-body">
        {children}
      </div>
    </div>
  );
}

// Usage — anything between tags is children
<Card title="User Profile">
  <p>Name: Sarah Chen</p>
  <p>Role: Admin</p>
  <button>Edit Profile</button>
</Card>
```

`children` is how you build wrapper/layout components. The parent decides the structure, the child provides the content.

### Common layout pattern

```jsx theme={null}
function PageLayout({ children }) {
  return (
    <div className="page">
      <Navbar />
      <main className="content">
        {children}
      </main>
      <Footer />
    </div>
  );
}

// Usage
<PageLayout>
  <h1>Dashboard</h1>
  <UserList />
</PageLayout>
```

## Props are read-only

Components must never modify their props. Props flow **down** from parent to child. A child can read them but not change them.

```jsx theme={null}
// ❌ Never do this
function UserCard({ name }) {
  name = "Modified"; // Don't modify props!
  return <h2>{name}</h2>;
}

// ✅ If you need to change data, use state (next lesson)
function UserCard({ name }) {
  const [displayName, setDisplayName] = useState(name);
  return <h2>{displayName}</h2>;
}
```

<Warning>
  Props are **read-only**. If a component needs to change data, it should use state (with `useState`). Props are for passing data down; state is for managing data that changes.
</Warning>

## Props vs state

|                         | Props                               | State                              |
| ----------------------- | ----------------------------------- | ---------------------------------- |
| **Defined by**          | Parent component                    | The component itself               |
| **Can change?**         | No (read-only)                      | Yes (via setter function)          |
| **Triggers re-render?** | Yes (when parent passes new values) | Yes (when setter is called)        |
| **Purpose**             | Configure a component from outside  | Manage data that changes over time |

Think of it like a function: props are the arguments passed in, state is the local variables inside.

## Passing props down multiple levels

Props flow from parent → child → grandchild:

```jsx theme={null}
function App() {
  const user = { name: "Sarah Chen", role: "Admin" };
  return <Dashboard user={user} />;
}

function Dashboard({ user }) {
  return (
    <div>
      <h1>Dashboard</h1>
      <UserCard name={user.name} role={user.role} />
    </div>
  );
}

function UserCard({ name, role }) {
  return (
    <div>
      <h2>{name}</h2>
      <span>{role}</span>
    </div>
  );
}
```

<Tip>
  If you find yourself passing props through many levels (prop drilling), it's a sign you might need to restructure your components or use React Context. For now, 2-3 levels of prop passing is perfectly fine.
</Tip>

## Spreading props

When you need to pass many props, spread them:

```jsx theme={null}
const userProps = {
  name: "Sarah Chen",
  email: "sarah@example.com",
  role: "Admin",
  isActive: true,
};

// Instead of listing each one
<UserCard name={userProps.name} email={userProps.email} role={userProps.role} isActive={userProps.isActive} />

// Spread them
<UserCard {...userProps} />
```

Useful when passing API data directly to a component.

## What's next?

Props let you pass data *into* components. But what about data that changes over time — form inputs, toggle states, fetched data? That's what state is for.

<Card title="Managing state with useState" icon="database" href="/react-essentials/use-state">
  Add interactive, dynamic data to your components
</Card>


# Setting up a React project
Source: https://js.maxbraglia.com/react-essentials/setup-react-project

Create a new React project with Vite and run it locally

## Create a React project in 60 seconds

We use **Vite** (pronounced "veet") as the build tool. It's fast, simple, and the recommended way to start React projects.

```bash theme={null}
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
npm run dev
```

Your app is now running at `http://localhost:5173`. Every time you save a file, the browser updates instantly.

<Info>
  Vite is to JavaScript what FastAPI is to Python — the modern, fast, no-nonsense choice. It replaces the older Create React App (CRA), which is no longer recommended.
</Info>

## Project structure

```
my-react-app/
├── node_modules/       # Dependencies (don't edit)
├── public/             # Static files (images, favicon)
├── src/
│   ├── App.jsx         # Your main component
│   ├── App.css         # Styles for App component
│   ├── main.jsx        # Entry point — renders App into the DOM
│   └── index.css       # Global styles
├── index.html          # The single HTML page
├── package.json        # Dependencies and scripts
└── vite.config.js      # Vite configuration
```

### The files that matter

**index.html** — The single HTML page. React renders everything into `<div id="root">`.

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>My React App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>
```

**src/main.jsx** — The entry point. Renders your App component into the root div.

```jsx theme={null}
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.jsx';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

<Info>
  `React.StrictMode` is a development-only helper. It may render components (and run effects) more than once in development to help catch bugs. This can look surprising at first, but it does not happen in production builds.
</Info>

**src/App.jsx** — Your main component. This is where you start building.

```jsx theme={null}
function App() {
  return (
    <div>
      <h1>Hello, React!</h1>
    </div>
  );
}

export default App;
```

<Tip>
  Start by editing `App.jsx`. Delete the default content and replace it with your own. You'll add more components as files in the `src/` folder and import them into `App.jsx`.
</Tip>

## The .jsx extension

React files use `.jsx` instead of `.js`. JSX lets you write HTML-like syntax inside JavaScript — you'll learn more in the next lesson.

```jsx theme={null}
// This is JSX — HTML inside JavaScript
function Greeting() {
  return <h1>Hello, World!</h1>;
}
```

<Info>
  `.jsx` and `.js` both work in Vite. The convention is `.jsx` for files that contain JSX (which is almost every React file). Some projects use `.tsx` for TypeScript + JSX.
</Info>

## Key scripts

Your `package.json` includes these scripts:

```bash theme={null}
npm run dev       # Start development server (hot reload)
npm run build     # Build for production
npm run preview   # Preview the production build locally
```

You'll spend 99% of your time using `npm run dev`.

## Adding your first component

Create a new file in `src/`:

```jsx theme={null}
// src/UserCard.jsx
function UserCard({ name, email }) {
  return (
    <div className="user-card">
      <h2>{name}</h2>
      <p>{email}</p>
    </div>
  );
}

export default UserCard;
```

Import and use it in `App.jsx`:

```jsx theme={null}
// src/App.jsx
import UserCard from './UserCard';

function App() {
  return (
    <div>
      <h1>My App</h1>
      <UserCard name="Sarah Chen" email="sarah@example.com" />
      <UserCard name="John Park" email="john@example.com" />
    </div>
  );
}

export default App;
```

That's the entire workflow: create a component file, export it, import it where you need it.

## Organizing components

As your app grows, create folders to organize:

```
src/
├── components/
│   ├── UserCard.jsx
│   ├── Navbar.jsx
│   └── Spinner.jsx
├── pages/
│   ├── Home.jsx
│   └── Settings.jsx
├── api/
│   └── users.js          # API functions (not React)
├── App.jsx
└── main.jsx
```

<Tip>
  Don't over-organize early. Start with all components in `src/`, and extract into folders when you have 10+ files. The folder structure isn't enforced by React — use whatever makes sense for your project.
</Tip>

## What's next?

Your project is running. Now let's learn the core building blocks — components and JSX.

<Card title="Components and JSX" icon="cube" href="/react-essentials/components-jsx">
  Build UI with reusable components using JSX syntax
</Card>


# Side effects with useEffect
Source: https://js.maxbraglia.com/react-essentials/use-effect

Fetch data, set up subscriptions, and run code when your component mounts

## What are side effects?

React components have one job: return JSX based on props and state. Anything else — fetching data, updating the document title, setting up a timer — is a **side effect**. It's something that happens *outside* the render cycle.

```jsx theme={null}
function UserList() {
  const [users, setUsers] = useState([]);

  // This is a side effect — fetching data from an API
  // Where does it go? useEffect.
}
```

`useEffect` is the hook for running side effects. In this course, you'll use it mostly for **fetching data** and **syncing with browser APIs** (like document title or timers).

<Info>
  Python mental model: your component function is like a function React may call many times to calculate UI. Keep that part "pure" (return JSX from props/state). `useEffect` is where you register code that should run **after render** to sync with the outside world (network, browser APIs, timers).
</Info>

## Basic useEffect

```jsx theme={null}
import { useState, useEffect } from 'react';

function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    // This runs after the component renders
    console.log("Component mounted!");
  }, []); // Empty array = run once on mount

  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
```

`useEffect` takes two arguments:

1. A **function** — the code to run (the effect)
2. A **dependency array** — when to re-run it

## The dependency array

The dependency array controls when the effect runs:

<Tip>
  Python mental model: the dependency array is the list of values React watches. You're telling React, "re-run this sync code when these inputs change."
</Tip>

```jsx theme={null}
// Runs once — when the component mounts
useEffect(() => {
  fetchUsers();
}, []);

// Runs when userId changes
useEffect(() => {
  fetchUser(userId);
}, [userId]);

// Runs when either userId or role changes
useEffect(() => {
  fetchUserData(userId, role);
}, [userId, role]);

// ⚠️ Runs on EVERY render (usually a mistake)
useEffect(() => {
  console.log("Rendered!");
}); // No array at all
```

| Dependency array | When it runs                           |
| ---------------- | -------------------------------------- |
| `[]`             | Once, when component mounts            |
| `[userId]`       | On mount + whenever `userId` changes   |
| `[a, b]`         | On mount + whenever `a` or `b` changes |
| *(omitted)*      | Every single render (rarely wanted)    |

<Info>
  In development, `React.StrictMode` may run mount effects twice to help reveal bugs. For a simple `useEffect(..., [])` data-fetch example, that can mean two requests in development unless you guard against it. Production does not do the extra development check.
</Info>

<Warning>
  `[]` is a common beginner pattern for "run on mount" effects (like an initial fetch), but it's not the default for every effect. As a rule: put every prop/state value your effect uses into the dependency array. Omitting the array entirely causes the effect to run on every render, which is usually a bug.
</Warning>

## Fetching data on mount

This is the pattern you'll use most often — load data when a component first appears:

```jsx theme={null}
import { useState, useEffect } from 'react';

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function loadUsers() {
      try {
        const response = await fetch("http://localhost:8000/api/users");
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        const data = await response.json();
        setUsers(data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    loadUsers();
  }, []); // Empty array = fetch once on mount

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

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name} — {user.email}</li>
      ))}
    </ul>
  );
}
```

<Info>
  Notice the async function is defined *inside* the useEffect callback, not as the callback itself. This is because useEffect callbacks can't be async directly — they need to return either nothing or a cleanup function.
</Info>

### Fetching based on a prop or state value

When the data depends on a value (like a user ID from the URL), include it in the dependency array:

```jsx theme={null}
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadUser() {
      setLoading(true);
      try {
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
        setUser(await response.json());
      } catch (err) {
        setUser(null);
      } finally {
        setLoading(false);
      }
    }

    loadUser();
  }, [userId]); // Re-fetch when userId changes

  if (loading) return <p>Loading...</p>;
  if (!user) return <p>User not found</p>;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}
```

When `userId` changes (e.g., navigating from one user profile to another), the effect runs again and fetches the new user.

## Other common side effects

### Updating the document title

```jsx theme={null}
function ProductPage({ product }) {
  useEffect(() => {
    document.title = `${product.name} — My Store`;
  }, [product.name]);

  return <h1>{product.name}</h1>;
}
```

### Setting up a timer

```jsx theme={null}
function Timer() {
  const [seconds, setSeconds] = useState(0);

  useEffect(() => {
    const interval = setInterval(() => {
      setSeconds(prev => prev + 1);
    }, 1000);

    // Cleanup: clear the interval when component unmounts
    return () => clearInterval(interval);
  }, []);

  return <p>Elapsed: {seconds}s</p>;
}
```

## Cleanup function

The function you return from useEffect runs when the component **unmounts** (disappears) or before the effect re-runs:

```jsx theme={null}
useEffect(() => {
  // Setup: runs when component mounts (or dependencies change)
  const subscription = connectToWebSocket(userId);

  // Cleanup: runs when component unmounts (or before next run)
  return () => {
    subscription.close();
  };
}, [userId]);
```

Cleanup prevents memory leaks and stale data. Common cleanup tasks:

* Clearing timers (`clearInterval`, `clearTimeout`)
* Closing WebSocket connections
* Cancelling pending requests
* Removing event listeners

<Tip>
  You won't need cleanup for most simple fetch-on-mount examples. Cleanup is mainly for subscriptions, timers, and event listeners. In development, StrictMode may re-run effects and expose problems earlier, but don't rely on it to catch every cleanup bug.
</Tip>

## Common mistakes

<AccordionGroup>
  <Accordion title="Missing dependency array — infinite loop">
    ```jsx theme={null}
    // ❌ Infinite loop: fetches on every render
    useEffect(() => {
      fetch("/api/users")
        .then(r => r.json())
        .then(data => setUsers(data)); // setUsers triggers re-render → effect runs again → ...
    });

    // ✅ Add empty dependency array
    useEffect(() => {
      fetch("/api/users")
        .then(r => r.json())
        .then(data => setUsers(data));
    }, []); // Only runs once
    ```

    <Warning>
      Forgetting the dependency array creates an infinite loop: render → effect → state update → re-render → effect → ... Your browser tab will freeze and your API will get hammered.
    </Warning>
  </Accordion>

  <Accordion title="Making useEffect callback async directly">
    ```jsx theme={null}
    // ❌ Wrong: useEffect callback can't be async
    useEffect(async () => {
      const response = await fetch("/api/users");
      const data = await response.json();
      setUsers(data);
    }, []);

    // ✅ Correct: define async function inside, then call it
    useEffect(() => {
      async function loadUsers() {
        const response = await fetch("/api/users");
        const data = await response.json();
        setUsers(data);
      }

      loadUsers();
    }, []);
    ```

    <Warning>
      `useEffect` callbacks must return either nothing or a cleanup function. An async function returns a Promise, which React doesn't know how to handle. Define the async function inside the effect and call it immediately.
    </Warning>
  </Accordion>

  <Accordion title="Object or array as dependency (re-runs every render)">
    ```jsx theme={null}
    // ❌ Runs on every render because {} !== {}
    const options = { page: 1, limit: 10 };
    useEffect(() => {
      fetchUsers(options);
    }, [options]); // New object every render!

    // ✅ Use primitive values as dependencies
    useEffect(() => {
      fetchUsers({ page, limit });
    }, [page, limit]); // Primitives are compared by value
    ```

    <Warning>
      Objects and arrays are compared by **reference**, not by value. `{a: 1} !== {a: 1}`. Use primitive values (strings, numbers, booleans) in the dependency array whenever possible.
    </Warning>
  </Accordion>
</AccordionGroup>

## The useEffect mental model

Think of useEffect in terms of **synchronization**, not lifecycle:

```
"Keep this side effect synchronized with these values"
```

* `useEffect(fn, [])` — synchronize with nothing (run once)
* `useEffect(fn, [userId])` — synchronize with userId (re-run when it changes)
* `useEffect(fn, [a, b])` — synchronize with a and b

<Tip>
  If you're coming from Python or other frameworks, resist thinking in "component lifecycle" terms (mount, update, unmount). Think instead: "this effect should run when these values change." The dependency array is the key to understanding useEffect.
</Tip>

<Info>
  Also remember: `useEffect` callbacks are closures. They capture values from the render where they were created. That's why missing a dependency can make an effect use an old value ("stale closure").
</Info>

## What's next?

You can fetch data and manage side effects. Now let's learn how to conditionally show different UI based on that data — loading spinners, error messages, and content.

<Card title="Conditional rendering" icon="code-branch" href="/react-essentials/conditional-rendering">
  Show different UI based on state and conditions
</Card>


# Managing state with useState
Source: https://js.maxbraglia.com/react-essentials/use-state

Add interactive, dynamic data to your React components

## What is state?

State is data that can change over time - a form input, a toggle button, items in a shopping cart. When state changes, React automatically updates the UI to match.

The `useState` hook is how you add state to function components. You'll use it constantly.

## Basic useState example

```jsx Counter.jsx theme={null}
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
      <button onClick={() => setCount(count - 1)}>
        Decrement
      </button>
      <button onClick={() => setCount(0)}>
        Reset
      </button>
    </div>
  );
}

export default Counter;
```

`useState(0)` returns an array with two items:

1. The current value (`count`)
2. A function to update it (`setCount`)

We use array destructuring to grab both: `const [count, setCount] = useState(0)`.

<Tip>
  Always name the setter function `set` + the state variable name: `count`/`setCount`, `user`/`setUser`, `isOpen`/`setIsOpen`. This is a strong convention in React.
</Tip>

## How state updates work

```jsx theme={null}
function Example() {
  const [count, setCount] = useState(0);
  
  const handleClick = () => {
    console.log('Before:', count); // 0
    setCount(5);
    console.log('After:', count);  // Still 0! 
  };
  
  return <button onClick={handleClick}>Set to 5</button>;
}
```

State updates are **scheduled** (and often batched). When you call `setCount(5)`, React schedules a re-render but doesn't update `count` immediately inside the current event handler. The new value will be available on the next render.

<Warning>
  Don't try to use the updated state value immediately after calling the setter in the same event handler. It won't be updated yet. React batches state updates for performance.
</Warning>

## Updating state based on previous value

```jsx theme={null}
function Counter() {
  const [count, setCount] = useState(0);
  
  // ❌ Wrong when updating multiple times
  const handleIncrement = () => {
    setCount(count + 1);
    setCount(count + 1); // Both use the same 'count' value!
  };
  
  // ✅ Correct: Use updater function
  const handleIncrementTwice = () => {
    setCount(prev => prev + 1); // Gets latest value
    setCount(prev => prev + 1); // Gets latest value
  };
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={handleIncrement}>Add 1 (broken)</button>
      <button onClick={handleIncrementTwice}>Add 2 (works)</button>
    </div>
  );
}
```

When updating based on the previous state, use the updater function form: `setCount(prev => prev + 1)`. This ensures you always get the latest value, even if multiple updates happen.

<Tip>
  If your new state depends on the old state, use the updater function: `setState(prev => ...)`. If it doesn't, you can pass the value directly: `setState(newValue)`.
</Tip>

## State with objects

```jsx UserProfile.jsx theme={null}
import { useState } from 'react';

function UserProfile() {
  const [user, setUser] = useState({
    name: "Sarah Doe",
    email: "sarah@example.com",
    age: 25
  });
  
  const updateAge = () => {
    // ❌ Wrong: Mutating state directly
    user.age = 26;
    
    // ✅ Correct: Create new object
    setUser({ ...user, age: 26 });
  };
  
  const updateName = (newName) => {
    setUser({ ...user, name: newName });
  };
  
  return (
    <div>
      <h2>{user.name}</h2>
      <p>Email: {user.email}</p>
      <p>Age: {user.age}</p>
      <button onClick={updateAge}>Increment Age</button>
    </div>
  );
}

export default UserProfile;
```

Never mutate state directly. Use the spread operator `...` to create a new object with the updated property. React only detects changes when you pass a new object to the setter.

<Warning>
  Direct mutation (`user.age = 26`) won't trigger a re-render. React compares the old and new values - if they're the same object reference, it thinks nothing changed.
</Warning>

## Multiple state variables

```jsx UserForm.jsx theme={null}
import { useState } from 'react';

function UserForm() {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState(null);
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    setIsSubmitting(true);
    setError(null);
    
    try {
      const response = await fetch('http://localhost:8000/api/users', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name, email }),
      });
      
      if (!response.ok) throw new Error('Failed to create user');
      
      // Clear form on success
      setName('');
      setEmail('');
    } catch (err) {
      setError(err.message);
    } finally {
      setIsSubmitting(false);
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Name"
        disabled={isSubmitting}
      />
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        disabled={isSubmitting}
      />
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Saving...' : 'Save'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </form>
  );
}

export default UserForm;
```

You can have as many `useState` calls as you need. Each one is independent. Here we track form inputs, loading state, and errors separately.

<Info>
  The `disabled={isSubmitting}` prevents users from submitting the form multiple times while a request is in flight. This is a crucial UX pattern.
</Info>

## State with arrays

```jsx TodoList.jsx theme={null}
import { useState } from 'react';

function TodoList() {
  const [todos, setTodos] = useState([
    { id: 1, text: "Learn JavaScript", done: false },
    { id: 2, text: "Build a project", done: false }
  ]);
  const [input, setInput] = useState('');
  
  const addTodo = () => {
    if (!input.trim()) return;
    
    const newTodo = {
      id: Date.now(),
      text: input,
      done: false
    };
    
    setTodos([...todos, newTodo]);
    setInput('');
  };
  
  const toggleTodo = (id) => {
    setTodos(todos.map(todo =>
      todo.id === id ? { ...todo, done: !todo.done } : todo
    ));
  };
  
  const deleteTodo = (id) => {
    setTodos(todos.filter(todo => todo.id !== id));
  };
  
  return (
    <div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Add a todo"
      />
      <button onClick={addTodo}>Add</button>
      
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>
            <input
              type="checkbox"
              checked={todo.done}
              onChange={() => toggleTodo(todo.id)}
            />
            <span style={{ textDecoration: todo.done ? 'line-through' : 'none' }}>
              {todo.text}
            </span>
            <button onClick={() => deleteTodo(todo.id)}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default TodoList;
```

For arrays, use array methods that return new arrays:

* Add item: `[...array, newItem]`
* Update item: `array.map(item => item.id === id ? updatedItem : item)`
* Remove item: `array.filter(item => item.id !== id)`

<Tip>
  Never use `.push()`, `.pop()`, `.splice()` or other mutating methods on state arrays. Always create a new array with spread `...` or array methods like `.map()` and `.filter()`.
</Tip>

## When to split state vs keep together

```jsx theme={null}
// ❌ Too granular - related data split up
function UserForm() {
  const [firstName, setFirstName] = useState('');
  const [lastName, setLastName] = useState('');
  const [email, setEmail] = useState('');
  const [phone, setPhone] = useState('');
  // ... many more individual states
}

// ✅ Better - group related data
function UserForm() {
  const [user, setUser] = useState({
    firstName: '',
    lastName: '',
    email: '',
    phone: ''
  });
  
  const updateField = (field, value) => {
    setUser({ ...user, [field]: value });
  };
}

// ✅ Also good - separate unrelated concerns
function UserForm() {
  const [user, setUser] = useState({ firstName: '', lastName: '', email: '' });
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState(null);
}
```

Group related data in objects, but keep unrelated concerns (like loading states and errors) separate.

## Common mistakes

<AccordionGroup>
  <Accordion title="Mutating state directly">
    ```jsx theme={null}
    // ❌ Wrong: Direct mutation
    const [user, setUser] = useState({ name: "Sarah", age: 25 });

    function updateAge() {
      user.age = 26; // React won't detect this!
      setUser(user); // Still the same object reference
    }

    // ✅ Correct: Create new object
    function updateAge() {
      setUser({ ...user, age: 26 });
    }
    ```

    <Warning>
      React only detects changes when you call the setter with a NEW object or array. Mutating the existing state and passing it back won't trigger a re-render because it's still the same reference.
    </Warning>
  </Accordion>

  <Accordion title="Using stale state in updates">
    ```jsx theme={null}
    // ❌ Wrong: Using current state value directly
    const [count, setCount] = useState(0);

    function incrementTwice() {
      setCount(count + 1); // Uses 0
      setCount(count + 1); // Also uses 0, because count hasn't updated yet
      // Result: count is 1, not 2
    }

    // ✅ Correct: Use updater function
    function incrementTwice() {
      setCount(prev => prev + 1); // Uses latest value
      setCount(prev => prev + 1); // Uses latest value
      // Result: count is 2
    }
    ```

    <Warning>
      When multiple state updates happen in the same function, use the updater function form to ensure you're always working with the latest value.
    </Warning>
  </Accordion>

  <Accordion title="Forgetting that state updates are asynchronous">
    ```jsx theme={null}
    // ❌ Wrong: Expecting immediate update
    function handleClick() {
      setCount(5);
      console.log(count); // Still the old value!
    }

    // ✅ Correct: Use the new value in next render
    function handleClick() {
      setCount(5);
      // Don't try to use the new value here
    }

    // The new value will be available in the next render:
    console.log(count); // This will show 5 on the next render
    ```

    <Warning>
      State updates are asynchronous. The new value won't be available until the component re-renders. Don't try to use the updated state immediately after calling the setter.
    </Warning>
  </Accordion>

  <Accordion title="Not using keys in lists">
    ```jsx theme={null}
    // ❌ Wrong: Missing key prop
    {todos.map(todo => (
      <li>{todo.text}</li>
    ))}

    // ✅ Correct: Include unique key
    {todos.map(todo => (
      <li key={todo.id}>{todo.text}</li>
    ))}
    ```

    <Warning>
      When rendering lists, each item needs a unique `key` prop. This helps React efficiently update the DOM when items are added, removed, or reordered. Never use array index as a key if the list can change.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

State lets you manage data within a component. Now let's learn how to fetch data from your backend when a component first loads.

<Card title="Side effects with useEffect" icon="download" href="/react-essentials/use-effect">
  Fetch data when your component mounts
</Card>


# What is React
Source: https://js.maxbraglia.com/react-essentials/what-is-react

Understand what React is, why it exists, and how it helps you build web apps

## The problem React solves

In the DOM section, you learned how to build interactive pages with vanilla JavaScript — selecting elements, updating text, creating nodes, attaching event listeners. It works, but it doesn't scale.

```javascript theme={null}
// Vanilla JavaScript — update a user card
function updateUser(user) {
  document.querySelector(".name").textContent = user.name;
  document.querySelector(".email").textContent = user.email;
  document.querySelector(".role").textContent = user.role;
  document.querySelector(".avatar").src = user.avatar;
  if (user.isAdmin) {
    document.querySelector(".badge").classList.remove("hidden");
  } else {
    document.querySelector(".badge").classList.add("hidden");
  }
}
```

For one component, this is manageable. For a page with 50 interactive elements, each affecting each other, it becomes a nightmare. You're manually tracking what changed and telling the browser exactly what to update.

**React flips this.** You describe what the UI should look like for any given state, and React figures out what needs to change in the DOM.

```jsx theme={null}
// React — describe the UI as a function of data
function UserCard({ user }) {
  return (
    <div className="user-card">
      <img src={user.avatar} alt={user.name} />
      <h3>{user.name}</h3>
      <p>{user.email}</p>
      <p>{user.role}</p>
      {user.isAdmin && <span className="badge">Admin</span>}
    </div>
  );
}
```

When `user` changes, React automatically updates the UI to match the new state. In day-to-day React UI code, you usually stop doing manual DOM updates with `document.querySelector` and `element.textContent`.

## Components: the building blocks

React apps are made of **components** — reusable, self-contained pieces of UI. Each component is a JavaScript function that returns what should appear on screen.

```
Your App
├── Navbar
│   ├── Logo
│   ├── NavLinks
│   └── UserMenu
├── Sidebar
│   ├── FilterPanel
│   └── CategoryList
└── MainContent
    ├── SearchBar
    ├── UserList
    │   ├── UserCard
    │   ├── UserCard
    │   └── UserCard
    └── Pagination
```

Every piece of your page is a component. Components can contain other components. This composability is what makes React scale — you build small, focused pieces and combine them.

<Info>
  If you've used Python classes, think of components like classes with a `render` method (though React components are actually just functions). Each one manages its own piece of the UI.
</Info>

## How React updates the page

React uses a **Virtual DOM** — a lightweight copy of the real DOM that lives in memory.

1. Your component renders and returns JSX (a description of the UI)
2. React creates a Virtual DOM from that JSX
3. When state changes, React re-renders the component and creates a new Virtual DOM
4. React **diffs** the old and new Virtual DOMs
5. React applies only the minimal changes to the real DOM

```jsx theme={null}
// When count changes from 3 to 4...
function Counter() {
  const [count, setCount] = useState(3);

  return (
    <div>
      <h1>Counter</h1>           {/* Unchanged — React skips this */}
      <p>Count: {count}</p>       {/* Changed — React updates only this text */}
      <button onClick={...}>+</button> {/* Unchanged — React skips this */}
    </div>
  );
}
```

React only touches the single text node that changed — not the entire component. This is why React apps feel fast even with complex UIs.

<Tip>
  You don't need to understand the Virtual DOM in detail. The key insight is: **you describe what the UI should look like, React handles updating the DOM efficiently.** That's the whole deal.
</Tip>

## Why React (specifically)

There are other frameworks (Vue, Angular, Svelte), but React dominates because:

* **Massive ecosystem** — solutions exist for almost every problem
* **Job market** — the most in-demand frontend skill
* **Stability** — backed by Meta, used by millions of apps
* **React Native** — the same concepts work for mobile apps
* **Community** — Stack Overflow, tutorials, and libraries everywhere

For connecting a React frontend to your FastAPI backend — which is what this course prepares you for — React is the most practical choice.

## The mental model shift

| Vanilla JavaScript                               | React                                               |
| ------------------------------------------------ | --------------------------------------------------- |
| **Imperative**: Tell the browser *how* to update | **Declarative**: Tell React *what* the UI should be |
| You manage DOM updates manually                  | React manages DOM updates for you                   |
| State scattered across DOM elements              | State lives in component variables                  |
| Event listeners attached manually                | Event handlers passed as props                      |
| Hard to keep UI in sync with data                | UI always reflects current state                    |

The biggest shift: **stop thinking in terms of DOM manipulation and start thinking in terms of data.** Your UI is a function of your data. When the data changes, the UI updates automatically.

## What you need to know

Here's the truth about React that nobody tells beginners: **90% of React development uses just a handful of concepts.**

The essentials you'll learn in this section:

1. **Components & JSX** — building blocks of the UI
2. **Props** — passing data into components
3. **useState** — managing data that changes
4. **useEffect** — fetching data and side effects
5. **Conditional rendering** — showing/hiding UI based on state
6. **List rendering** — displaying arrays of data
7. **Forms** — handling user input
8. **Component composition** — organizing your app

That's it. Master these, and you can build any standard web application. Everything else (context, reducers, suspense, server components) is situational — learn it when you need it.

## What's next?

Let's get a React project running on your machine. In under 2 minutes you'll have a live development server with hot reload.

<Card title="Setting up a React project" icon="rocket" href="/react-essentials/setup-react-project">
  Create a new React project with Vite
</Card>


# Array methods
Source: https://js.maxbraglia.com/working-with-data/array-methods

Transform, filter, and manipulate arrays with the essential 20% of methods

## The methods you'll use every day

JavaScript arrays have dozens of methods, but you'll use about six of them 90% of the time. These are the ones that matter for web development and React.

Every method here takes a callback function — an arrow function that runs once for each item in the array.

## .map() — transform each item

`.map()` creates a **new array** by transforming every item. Use it when you need to convert data from one shape to another.

```javascript theme={null}
const prices = [10, 20, 30, 40];
const withTax = prices.map(price => price * 1.08);
console.log(withTax); // [10.8, 21.6, 32.4, 43.2]

const names = ["sarah", "john", "alice"];
const capitalized = names.map(name => name.charAt(0).toUpperCase() + name.slice(1));
console.log(capitalized); // ["Sarah", "John", "Alice"]
```

### Real-world: formatting API data

```javascript theme={null}
const apiUsers = [
  { id: 1, first_name: "Sarah", last_name: "Chen" },
  { id: 2, first_name: "John", last_name: "Smith" },
];

const displayNames = apiUsers.map(user => ({
  id: user.id,
  fullName: `${user.first_name} ${user.last_name}`,
}));

console.log(displayNames);
// [{ id: 1, fullName: "Sarah Chen" }, { id: 2, fullName: "John Smith" }]
```

In React, you'll use `.map()` to render lists:

```jsx theme={null}
{users.map(user => (
  <li key={user.id}>{user.fullName}</li>
))}
```

<Tip>
  `.map()` always returns a new array with the same number of items. It never modifies the original. This is exactly what React needs for rendering lists.
</Tip>

## .filter() — keep matching items

`.filter()` creates a **new array** with only the items that pass a test. The callback must return `true` or `false`.

```javascript theme={null}
const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

const evens = numbers.filter(n => n % 2 === 0);
console.log(evens); // [2, 4, 6, 8, 10]

const bigNumbers = numbers.filter(n => n > 5);
console.log(bigNumbers); // [6, 7, 8, 9, 10]
```

### Real-world: filtering a user list

```javascript theme={null}
const users = [
  { name: "Sarah", role: "admin", active: true },
  { name: "John", role: "editor", active: false },
  { name: "Alice", role: "admin", active: true },
  { name: "Bob", role: "viewer", active: true },
];

const activeAdmins = users.filter(user => user.role === "admin" && user.active);
console.log(activeAdmins);
// [{ name: "Sarah", role: "admin", active: true }, { name: "Alice", role: "admin", active: true }]
```

<Info>
  `.filter()` can return fewer items, the same number, or even an empty array. It never modifies the original.
</Info>

## .find() — get the first match

`.find()` returns the **first item** that matches. Unlike `.filter()`, it returns a single item (or `undefined` if nothing matches).

```javascript theme={null}
const users = [
  { id: 1, name: "Sarah", role: "admin" },
  { id: 2, name: "John", role: "editor" },
  { id: 3, name: "Alice", role: "viewer" },
];

const admin = users.find(user => user.role === "admin");
console.log(admin); // { id: 1, name: "Sarah", role: "admin" }

const manager = users.find(user => user.role === "manager");
console.log(manager); // undefined
```

Use `.find()` when you need one specific item — looking up a user by ID, finding a product by slug, getting the current route.

```javascript theme={null}
// Common pattern: find by ID
const userId = 2;
const user = users.find(u => u.id === userId);
```

<Warning>
  `.find()` returns `undefined` if no item matches — not `null`, not an error. Always handle the "not found" case.
</Warning>

## .forEach() — do something with each item

`.forEach()` runs a function for each item but **doesn't return anything**. Use it for side effects like logging or DOM manipulation.

```javascript theme={null}
const tasks = ["Buy groceries", "Write code", "Walk the dog"];

tasks.forEach(task => {
  console.log(`- ${task}`);
});
// - Buy groceries
// - Write code
// - Walk the dog
```

```javascript theme={null}
// With index
const scores = [85, 92, 78, 95];
scores.forEach((score, index) => {
  console.log(`Student ${index + 1}: ${score}`);
});
```

<Tip>
  If you need a new array, use `.map()`. If you need to do something with each item (log, send, update DOM), use `.forEach()`. The rule: `.map()` transforms, `.forEach()` performs actions.
</Tip>

## .includes() — check if item exists

```javascript theme={null}
const permissions = ["read", "write", "delete"];

console.log(permissions.includes("write"));  // true
console.log(permissions.includes("admin"));  // false

// Use in conditionals
if (permissions.includes("delete")) {
  console.log("User can delete items");
}
```

Simple and readable. Works great for checking roles, features, or any "is this in the list?" question.

## .reduce() — combine into a single value

`.reduce()` takes an array and reduces it down to a single value — a total, an object, a string, whatever you need.

```javascript theme={null}
const prices = [29.99, 49.99, 9.99, 79.99];

const total = prices.reduce((sum, price) => sum + price, 0);
console.log(total); // 169.96
```

The callback takes two arguments:

1. **Accumulator** (`sum`) — the running result
2. **Current item** (`price`) — the current array element

The second argument to `.reduce()` (`0`) is the initial value of the accumulator.

### More reduce examples

```javascript theme={null}
// Count occurrences
const votes = ["yes", "no", "yes", "yes", "no", "yes"];
const tally = votes.reduce((counts, vote) => {
  counts[vote] = (counts[vote] || 0) + 1;
  return counts;
}, {});
console.log(tally); // { yes: 4, no: 2 }

// Find the maximum
const scores = [72, 95, 88, 61, 93];
const highest = scores.reduce((max, score) => score > max ? score : max, 0);
console.log(highest); // 95
```

<Info>
  `.reduce()` is powerful but can be hard to read. If a `.map()` + `.filter()` combination does the job, prefer that over `.reduce()`. Readability matters more than cleverness.
</Info>

## Chaining methods

Array methods return arrays, so you can chain them:

```javascript theme={null}
const products = [
  { name: "Laptop", price: 999, inStock: true },
  { name: "Phone", price: 699, inStock: false },
  { name: "Tablet", price: 499, inStock: true },
  { name: "Watch", price: 299, inStock: true },
];

// Get names of in-stock products under $500
const affordable = products
  .filter(p => p.inStock)
  .filter(p => p.price < 500)
  .map(p => p.name);

console.log(affordable); // ["Tablet", "Watch"]
```

Read chains top to bottom: start with all products → keep only in-stock → keep only under \$500 → extract names.

## Common mistakes

<AccordionGroup>
  <Accordion title="Forgetting to return in .map()">
    ```javascript theme={null}
    // ❌ Wrong: Curly braces but no return
    const doubled = [1, 2, 3].map(n => {
      n * 2; // Computes but doesn't return
    });
    console.log(doubled); // [undefined, undefined, undefined]

    // ✅ Correct: Add return with curly braces
    const doubled = [1, 2, 3].map(n => {
      return n * 2;
    });

    // ✅ Or use implicit return (no curly braces)
    const doubled = [1, 2, 3].map(n => n * 2);
    ```

    <Warning>
      This is the same arrow function gotcha from earlier. With curly braces, you need `return`. Without curly braces, the return is implicit. This mistake causes arrays of `undefined`.
    </Warning>
  </Accordion>

  <Accordion title="Using .map() when you need .forEach()">
    ```javascript theme={null}
    // ❌ Wrong: Using map for side effects (the returned array is wasted)
    users.map(user => {
      console.log(user.name);
    });

    // ✅ Correct: Use forEach for side effects
    users.forEach(user => {
      console.log(user.name);
    });
    ```

    <Warning>
      `.map()` creates and returns a new array. If you don't need that array, use `.forEach()` instead. Using `.map()` for side effects is wasteful and signals to other developers that you intended to transform data.
    </Warning>
  </Accordion>

  <Accordion title="Mutating the original array by mistake">
    ```javascript theme={null}
    // ❌ Wrong: .sort() mutates the original array
    const scores = [85, 92, 78, 95];
    const sorted = scores.sort((a, b) => a - b);
    console.log(scores); // [78, 85, 92, 95] — original is modified!

    // ✅ Correct: Copy first, then sort
    const sorted = [...scores].sort((a, b) => a - b);
    console.log(scores); // [85, 92, 78, 95] — original unchanged
    ```

    <Warning>
      `.sort()`, `.reverse()`, `.splice()`, `.push()`, and `.pop()` all mutate the original array. If you need the original intact, spread it into a new array first: `[...arr].sort()`.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

Arrays handle lists. Now let's learn about objects — JavaScript's key-value data structure for representing entities like users, products, and API responses.

<Card title="Objects" icon="cube" href="/working-with-data/objects">
  Store data as key-value pairs
</Card>


# Arrays
Source: https://js.maxbraglia.com/working-with-data/arrays

Store and access ordered collections of data with JavaScript arrays

## What are arrays?

Arrays store multiple values in a single variable. You'll use them constantly — lists of users, product catalogs, API responses, form options, navigation items. Any time you have a collection of things, that's an array.

```javascript theme={null}
const fruits = ["Apple", "Banana", "Cherry"];
const prices = [29.99, 49.99, 9.99];
const mixed = ["Sarah", 28, true, null]; // Can mix types (but usually don't)
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const users = ["Sarah", "John", "Alice"];
    console.log(users); // ["Sarah", "John", "Alice"]
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    users = ["Sarah", "John", "Alice"]
    print(users)  # ["Sarah", "John", "Alice"]
    ```
  </Tab>
</Tabs>

JavaScript arrays are Python lists. Same square bracket syntax, same zero-based indexing, same idea.

## Accessing items

```javascript theme={null}
const users = ["Sarah", "John", "Alice", "Bob"];

console.log(users[0]); // "Sarah"  (first item)
console.log(users[1]); // "John"   (second item)
console.log(users[3]); // "Bob"    (last item)
console.log(users[4]); // undefined (out of bounds — no error!)
```

<Warning>
  Accessing an index that doesn't exist returns `undefined` instead of throwing an error. This is different from Python, which raises an `IndexError`. It can lead to silent bugs if you're not careful.
</Warning>

### Getting the last item

```javascript theme={null}
const users = ["Sarah", "John", "Alice"];

// Classic way
console.log(users[users.length - 1]); // "Alice"

// Modern way (ES2022)
console.log(users.at(-1)); // "Alice"
console.log(users.at(-2)); // "John"
```

<Tip>
  `.at()` supports negative indices just like Python. Use `.at(-1)` to get the last item instead of the awkward `arr[arr.length - 1]`.
</Tip>

## Array length

```javascript theme={null}
const users = ["Sarah", "John", "Alice"];
console.log(users.length); // 3

// Check if array is empty
if (users.length === 0) {
  console.log("No users found");
}

// Common pattern: check before accessing
const firstUser = users.length > 0 ? users[0] : "No users";
```

Note: `.length` is a property, not a method. No parentheses needed.

## Modifying arrays

```javascript theme={null}
const colors = ["red", "green", "blue"];

// Add to the end
colors.push("yellow");
console.log(colors); // ["red", "green", "blue", "yellow"]

// Remove from the end
const last = colors.pop();
console.log(last);   // "yellow"
console.log(colors); // ["red", "green", "blue"]

// Add to the beginning
colors.unshift("white");
console.log(colors); // ["white", "red", "green", "blue"]

// Remove from the beginning
const first = colors.shift();
console.log(first);  // "white"
console.log(colors); // ["red", "green", "blue"]
```

| Method           | What it does          | Returns      |
| ---------------- | --------------------- | ------------ |
| `.push(item)`    | Add to end            | New length   |
| `.pop()`         | Remove from end       | Removed item |
| `.unshift(item)` | Add to beginning      | New length   |
| `.shift()`       | Remove from beginning | Removed item |

<Warning>
  These methods **mutate** the original array. In React, you'll avoid them and use non-mutating patterns instead (spread operator, `.filter()`, `.map()`). More on that when you learn React state.
</Warning>

## Checking if something is in an array

```javascript theme={null}
const roles = ["admin", "editor", "viewer"];

console.log(roles.includes("admin"));   // true
console.log(roles.includes("manager")); // false

// Find the position of an item
console.log(roles.indexOf("editor")); // 1
console.log(roles.indexOf("manager")); // -1 (not found)
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const roles = ["admin", "editor", "viewer"];
    roles.includes("admin"); // true
    roles.indexOf("admin");  // 0
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    roles = ["admin", "editor", "viewer"]
    "admin" in roles  # True
    roles.index("admin")  # 0
    ```
  </Tab>
</Tabs>

JavaScript uses `.includes()` where Python uses `in`. Both check for existence.

## Slicing arrays

```javascript theme={null}
const numbers = [10, 20, 30, 40, 50];

// .slice(start, end) — end is exclusive
console.log(numbers.slice(1, 3));  // [20, 30]
console.log(numbers.slice(2));     // [30, 40, 50]
console.log(numbers.slice(-2));    // [40, 50]
console.log(numbers.slice());      // [10, 20, 30, 40, 50] (shallow copy)
```

`.slice()` returns a new array without modifying the original. Same behavior as Python's `list[1:3]`, just with method syntax instead of bracket notation.

## What's next?

You can create and access arrays. Now let's learn the methods that make arrays truly powerful — `.map()`, `.filter()`, `.find()`, and more.

<Card title="Array methods" icon="wand-magic-sparkles" href="/working-with-data/array-methods">
  Transform, filter, and search arrays
</Card>


# Conditionals
Source: https://js.maxbraglia.com/working-with-data/conditionals

Make decisions in your code with if/else, ternary operators, and logical operators

## if/else

Same concept as Python, different syntax:

```javascript theme={null}
const age = 25;

if (age >= 18) {
  console.log("Welcome");
} else {
  console.log("Too young");
}
// "Welcome"
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    if (score >= 90) {
      grade = "A";
    } else if (score >= 80) {
      grade = "B";
    } else if (score >= 70) {
      grade = "C";
    } else {
      grade = "F";
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    if score >= 90:
        grade = "A"
    elif score >= 80:
        grade = "B"
    elif score >= 70:
        grade = "C"
    else:
        grade = "F"
    ```
  </Tab>
</Tabs>

Two differences: curly braces instead of colons and indentation, and `else if` instead of `elif`.

### Conditions must be in parentheses

```javascript theme={null}
// Parentheses around the condition are required
if (user.isAdmin) {
  showAdminPanel();
}

// Python doesn't require them
// if user.is_admin:
//     show_admin_panel()
```

## Truthy and falsy values

JavaScript evaluates any value as `true` or `false` in a condition. This matters more than you'd expect.

**Falsy values** (evaluate to `false`):

```javascript theme={null}
if (false)     // false
if (0)         // false
if ("")        // false (empty string)
if (null)      // false
if (undefined) // false
if (NaN)       // false
```

**Everything else is truthy** — including some surprises:

```javascript theme={null}
if ("hello")   // true — any non-empty string
if (42)        // true — any non-zero number
if ([])        // true — empty array!
if ({})        // true — empty object!
```

<Warning>
  Empty arrays `[]` and empty objects `{}` are **truthy** in JavaScript. This is different from Python, where empty lists and dicts are falsy. To check if an array is empty, use `array.length === 0`.
</Warning>

### Practical use of truthy/falsy

```javascript theme={null}
// Check if a variable has a useful value
const username = getUserInput();

if (username) {
  console.log(`Hello, ${username}`);
} else {
  console.log("Please enter a username");
}

// Check if an array has items
const users = await fetchUsers();

if (users.length) { // 0 is falsy, any other number is truthy
  renderUserList(users);
} else {
  renderEmptyState();
}
```

## Ternary operator

A one-line if/else. You'll use this constantly in React for conditional rendering.

```javascript theme={null}
const age = 25;
const status = age >= 18 ? "adult" : "minor";
console.log(status); // "adult"
```

The syntax: `condition ? valueIfTrue : valueIfFalse`

```javascript theme={null}
// Setting variables
const greeting = user ? `Hello, ${user.name}` : "Hello, guest";

// Template literals
console.log(`Status: ${isActive ? "Active" : "Inactive"}`);

// Function arguments
fetchUsers(isAdmin ? "/api/admin/users" : "/api/users");
```

### Ternary in React

This is where the ternary operator really shines:

```jsx theme={null}
function UserGreeting({ user }) {
  return (
    <div>
      {user ? (
        <h1>Welcome back, {user.name}!</h1>
      ) : (
        <h1>Please log in</h1>
      )}
    </div>
  );
}
```

<Tip>
  Keep ternaries simple — one condition, two outcomes. If you need more complex logic, use an `if/else` block or extract the logic into a separate function.
</Tip>

## Logical operators

### && (AND) — short-circuit rendering

Returns the second value if the first is truthy. Otherwise returns the first.

```javascript theme={null}
const isLoggedIn = true;
const message = isLoggedIn && "Welcome back!";
console.log(message); // "Welcome back!"

const isLoggedIn = false;
const message = isLoggedIn && "Welcome back!";
console.log(message); // false
```

In React, `&&` is the most common way to conditionally show something:

```jsx theme={null}
{isLoading && <Spinner />}
{error && <ErrorMessage text={error} />}
{users.length > 0 && <UserList users={users} />}
```

### || (OR) — fallback values

Returns the first truthy value.

```javascript theme={null}
const username = inputValue || "Anonymous";
const theme = savedTheme || "light";
const port = process.env.PORT || 3000;
```

<Warning>
  `||` treats `0`, `""`, and `false` as falsy — so `0 || 5` returns `5`, not `0`. If you need to only fall back on `null`/`undefined`, use `??` instead.
</Warning>

### ?? (nullish coalescing) — null/undefined fallback

Returns the right side only if the left is `null` or `undefined`. Doesn't trigger on `0`, `""`, or `false`.

```javascript theme={null}
const count = 0;

console.log(count || 10);  // 10 — treats 0 as falsy
console.log(count ?? 10);  // 0  — only falls back on null/undefined

const name = "";
console.log(name || "Anonymous");  // "Anonymous" — treats "" as falsy
console.log(name ?? "Anonymous");  // "" — only falls back on null/undefined
```

<Tip>
  Use `??` when a value of `0`, `""`, or `false` is valid and shouldn't be replaced. Use `||` when you want any falsy value to trigger the fallback.
</Tip>

## switch statements

For multiple conditions against the same value:

```javascript theme={null}
const status = "processing";

switch (status) {
  case "pending":
    console.log("Waiting for review");
    break;
  case "processing":
    console.log("Being processed");
    break;
  case "completed":
    console.log("Done!");
    break;
  default:
    console.log("Unknown status");
}
// "Being processed"
```

<Warning>
  Don't forget `break` after each case. Without it, execution "falls through" to the next case. This is a common source of bugs.
</Warning>

## What's next?

You can make decisions with conditionals. Now let's learn how to repeat actions with loops.

<Card title="Loops" icon="rotate" href="/working-with-data/loops">
  Iterate over data with for loops and more
</Card>


# Destructuring
Source: https://js.maxbraglia.com/working-with-data/destructuring

Extract values from objects and arrays into individual variables

## Why destructuring?

Destructuring lets you unpack values from objects and arrays into separate variables in a single line. Instead of writing `user.name`, `user.email`, `user.role` over and over, you extract them once.

```javascript theme={null}
const user = { name: "Sarah", email: "sarah@example.com", role: "admin" };

// ❌ Without destructuring — repetitive
const name = user.name;
const email = user.email;
const role = user.role;

// ✅ With destructuring — one line
const { name, email, role } = user;

console.log(name);  // "Sarah"
console.log(email); // "sarah@example.com"
console.log(role);  // "admin"
```

## Object destructuring

Pull specific properties out of an object by name:

<Info>
  Python mental model: object destructuring is like doing multiple `dict` lookups and assignments in one step (`name = user["name"]`, `email = user["email"]`) — but with a much shorter syntax.
</Info>

```javascript theme={null}
const product = {
  id: 42,
  name: "Wireless Headphones",
  price: 79.99,
  category: "Electronics",
  inStock: true,
};

// Grab only what you need
const { name, price, inStock } = product;

console.log(name);    // "Wireless Headphones"
console.log(price);   // 79.99
console.log(inStock); // true
// id and category are ignored
```

### Renaming variables

When the property name conflicts with an existing variable or you want a clearer name:

```javascript theme={null}
const apiResponse = { data: [...], error: null, status: 200 };

// Rename "data" to "users" and "status" to "httpStatus"
const { data: users, status: httpStatus } = apiResponse;

console.log(users);      // [...]
console.log(httpStatus);  // 200
```

### Default values

Set fallbacks for properties that might not exist:

```javascript theme={null}
const settings = { theme: "dark" };

const { theme, language = "en", fontSize = 14 } = settings;

console.log(theme);    // "dark" (from the object)
console.log(language); // "en" (default — not in object)
console.log(fontSize); // 14 (default — not in object)
```

<Tip>
  Python mental model: this is similar to `settings.get("language", "en")`. One key difference: destructuring defaults only apply when the property is `undefined` (missing). If the value is explicitly `null`, the default is **not** used.
</Tip>

### Nested destructuring

```javascript theme={null}
const order = {
  id: "ORD-001",
  customer: {
    name: "Sarah Chen",
    address: { city: "Portland", state: "OR" },
  },
};

const { customer: { name, address: { city } } } = order;

console.log(name); // "Sarah Chen"
console.log(city); // "Portland"
```

<Tip>
  Don't go more than two levels deep with nested destructuring. It quickly becomes unreadable. For deeply nested data, destructure in multiple steps or use dot notation.
</Tip>

## Array destructuring

Pull values out by position:

<Info>
  Python mental model: this is like tuple unpacking (`first, second = values`) — but JavaScript adds useful extras like skipping items and collecting "the rest" with `...remaining`.
</Info>

```javascript theme={null}
const colors = ["red", "green", "blue"];

const [first, second, third] = colors;

console.log(first);  // "red"
console.log(second); // "green"
console.log(third);  // "blue"
```

### Skipping items

```javascript theme={null}
const scores = [95, 87, 72, 91, 88];

// Skip the first two
const [, , third] = scores;
console.log(third); // 72

// Get first and rest
const [best, ...remaining] = scores;
console.log(best);      // 95
console.log(remaining);  // [87, 72, 91, 88]
```

### Swapping variables

```javascript theme={null}
let a = 1;
let b = 2;

[a, b] = [b, a];

console.log(a); // 2
console.log(b); // 1
```

## Where you'll use destructuring every day

### React's useState

You've already seen this — it's array destructuring:

```jsx theme={null}
const [count, setCount] = useState(0);
const [user, setUser] = useState(null);
const [isLoading, setIsLoading] = useState(false);
```

`useState` returns a two-element array: `[currentValue, setterFunction]`. Destructuring gives them meaningful names.

### React component props

```jsx theme={null}
// Without destructuring
function UserCard(props) {
  return <h2>{props.name}</h2>;
}

// With destructuring — cleaner
function UserCard({ name, email, role }) {
  return (
    <div>
      <h2>{name}</h2>
      <p>{email}</p>
      <span>{role}</span>
    </div>
  );
}
```

### Function parameters

```javascript theme={null}
// Extract what you need in the parameter list
function displayOrder({ id, customer, total }) {
  console.log(`Order ${id} for ${customer}: $${total}`);
}

displayOrder({ id: "ORD-001", customer: "Sarah", total: 149.99, items: [...] });
// "Order ORD-001 for Sarah: $149.99"
```

<Tip>
  If you're coming from Python, this feels like writing `def display_order(order): ...` and immediately doing `id = order["id"]`, `customer = order["customer"]`, `total = order["total"]` at the top of the function.
</Tip>

### API responses

```javascript theme={null}
async function getUser(userId) {
  const response = await fetch(`/api/users/${userId}`);
  const { name, email, role } = await response.json();
  return { name, email, role };
}
```

## Comparing to Python

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Object destructuring (no Python equivalent)
    const { name, age } = user;

    // Array destructuring
    const [first, second] = [1, 2];

    // In function params
    function greet({ name, age }) {
      return `${name} is ${age}`;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # No dict destructuring — must access individually
    name = user["name"]
    age = user["age"]

    # Tuple unpacking (similar to array destructuring)
    first, second = (1, 2)

    # No param destructuring — access dict keys
    def greet(user):
        return f"{user['name']} is {user['age']}"
    ```
  </Tab>
</Tabs>

Object destructuring is one of the biggest syntax wins JavaScript has over Python. It's everywhere in React code.

## What's next?

Destructuring unpacks values *out of* objects and arrays. The spread operator does the opposite — it expands them *into* new structures.

<Card title="Spread operator" icon="expand" href="/working-with-data/spread-operator">
  Copy, merge, and expand arrays and objects
</Card>


# JSON basics
Source: https://js.maxbraglia.com/working-with-data/json-basics

Understand JSON format and how to convert between JSON and JavaScript objects

## What is JSON?

JSON (JavaScript Object Notation) is a text format for exchanging data between systems. When your React frontend talks to your FastAPI backend, the data travels as JSON strings over HTTP.

```json theme={null}
{
  "name": "Sarah Chen",
  "email": "sarah@example.com",
  "age": 28,
  "roles": ["admin", "editor"],
  "active": true
}
```

JSON looks like a JavaScript object, but it's a **string**. Every key must be in double quotes. No trailing commas, no comments, no functions — just data.

<Info>
  JSON is language-independent. Python uses `json.dumps()` and `json.loads()`. JavaScript uses `JSON.stringify()` and `JSON.parse()`. FastAPI automatically converts Pydantic models to JSON responses.
</Info>

## JSON.stringify() — object to string

Convert a JavaScript object into a JSON string. You do this when **sending** data to an API.

```javascript theme={null}
const user = {
  name: "Sarah Chen",
  age: 28,
  isAdmin: true,
  tags: ["developer", "admin"],
};

const jsonString = JSON.stringify(user);
console.log(jsonString);
// '{"name":"Sarah Chen","age":28,"isAdmin":true,"tags":["developer","admin"]}'

console.log(typeof jsonString); // "string"
```

### Pretty printing

```javascript theme={null}
// Readable format with 2-space indentation
const pretty = JSON.stringify(user, null, 2);
console.log(pretty);
// {
//   "name": "Sarah Chen",
//   "age": 28,
//   "isAdmin": true,
//   "tags": [
//     "developer",
//     "admin"
//   ]
// }
```

The third argument controls indentation. Useful for debugging and logging.

### Where you'll use it

```javascript theme={null}
// Sending data to your FastAPI backend
const response = await fetch("http://localhost:8000/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Sarah", email: "sarah@example.com" }),
});
```

The `body` of a fetch request must be a string. `JSON.stringify()` converts your object to the JSON string the server expects.

## JSON.parse() — string to object

Convert a JSON string back into a JavaScript object. You do this when **receiving** data from an API.

```javascript theme={null}
const jsonString = '{"name":"Sarah Chen","age":28,"isAdmin":true}';

const user = JSON.parse(jsonString);
console.log(user.name);    // "Sarah Chen"
console.log(user.age);     // 28
console.log(user.isAdmin); // true
console.log(typeof user);  // "object"
```

### Where you'll use it

```javascript theme={null}
// Reading data from your FastAPI backend
const response = await fetch("http://localhost:8000/api/users");
const users = await response.json(); // This calls JSON.parse() internally

console.log(users); // Array of user objects
```

<Tip>
  You rarely call `JSON.parse()` directly. The `response.json()` method from `fetch` does it for you. But you'll use `JSON.parse()` when reading from localStorage or processing raw JSON strings.
</Tip>

## JSON and localStorage

`localStorage` can only store strings. Use `JSON.stringify()` and `JSON.parse()` to save and load objects:

```javascript theme={null}
// Save to localStorage
const settings = { theme: "dark", fontSize: 16 };
localStorage.setItem("settings", JSON.stringify(settings));

// Load from localStorage
const saved = localStorage.getItem("settings");
const loadedSettings = JSON.parse(saved);
console.log(loadedSettings.theme); // "dark"
```

## What JSON can't store

JSON only supports a subset of JavaScript data types:

| Supported                  | Not supported                   |
| -------------------------- | ------------------------------- |
| Strings, numbers, booleans | `undefined`                     |
| `null`                     | Functions                       |
| Arrays                     | `Date` objects (become strings) |
| Plain objects              | `Map`, `Set`                    |

```javascript theme={null}
const data = {
  name: "Sarah",
  callback: function() {},  // Dropped
  date: new Date(),          // Becomes a string
  nothing: undefined,        // Dropped
};

console.log(JSON.stringify(data));
// '{"name":"Sarah","date":"2024-01-15T12:00:00.000Z"}'
```

<Warning>
  `undefined` and functions are silently dropped during `JSON.stringify()`. Dates become ISO strings. If you `JSON.parse()` a date string, you get a string back — not a Date object. Convert it manually with `new Date(dateString)`.
</Warning>

## Common mistakes

<AccordionGroup>
  <Accordion title="Parsing a value that's already an object">
    ```javascript theme={null}
    // ❌ Wrong: response.json() already parsed it
    const response = await fetch("/api/users");
    const data = await response.json();
    const users = JSON.parse(data); // Error! data is already an object

    // ✅ Correct: response.json() handles the parsing
    const response = await fetch("/api/users");
    const users = await response.json(); // Already an object
    ```

    <Warning>
      `response.json()` calls `JSON.parse()` internally. Don't double-parse. If you have an object, you don't need `JSON.parse()`. If you have a string, you do.
    </Warning>
  </Accordion>

  <Accordion title="Forgetting to stringify when saving to localStorage">
    ```javascript theme={null}
    // ❌ Wrong: Saving object directly
    const user = { name: "Sarah", age: 28 };
    localStorage.setItem("user", user);
    console.log(localStorage.getItem("user")); // "[object Object]" — useless

    // ✅ Correct: Stringify first
    localStorage.setItem("user", JSON.stringify(user));
    const loaded = JSON.parse(localStorage.getItem("user"));
    console.log(loaded.name); // "Sarah"
    ```

    <Warning>
      localStorage only stores strings. If you pass an object, JavaScript calls `.toString()` on it, which gives you the useless string `"[object Object]"`. Always stringify.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's next?

You can convert data between JavaScript objects and JSON strings. Now let's learn how to make decisions in your code with conditionals.

<Card title="Conditionals" icon="code-branch" href="/working-with-data/conditionals">
  if/else, ternary operators, and logical operators
</Card>


# Loops
Source: https://js.maxbraglia.com/working-with-data/loops

Repeat actions and iterate over data with JavaScript loops

## Looping in JavaScript

Loops let you repeat actions and iterate over data. JavaScript has several loop types, but you'll use two of them most of the time: `for...of` and the classic `for` loop.

## for...of — iterate over arrays

The cleanest way to loop through an array:

```javascript theme={null}
const fruits = ["Apple", "Banana", "Cherry"];

for (const fruit of fruits) {
  console.log(fruit);
}
// Apple
// Banana
// Cherry
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    for (const item of items) {
      console.log(item);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    for item in items:
        print(item)
    ```
  </Tab>
</Tabs>

JavaScript's `for...of` is Python's `for...in`. Same concept, different keyword. Use `const` for the loop variable if you don't need to reassign it inside the loop.

### When you need the index

```javascript theme={null}
const users = ["Sarah", "John", "Alice"];

// Use .forEach() with index
users.forEach((user, index) => {
  console.log(`${index + 1}. ${user}`);
});
// 1. Sarah
// 2. John
// 3. Alice

// Or use .entries()
for (const [index, user] of users.entries()) {
  console.log(`${index + 1}. ${user}`);
}
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    for (const [index, user] of users.entries()) {
      console.log(`${index}: ${user}`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    for index, user in enumerate(users):
        print(f"{index}: {user}")
    ```
  </Tab>
</Tabs>

`.entries()` is JavaScript's equivalent of Python's `enumerate()`.

## for...in — iterate over object keys

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };

for (const key in user) {
  console.log(`${key}: ${user[key]}`);
}
// name: Sarah
// age: 28
// role: admin
```

<Warning>
  `for...in` is for **objects**. `for...of` is for **arrays**. Mixing them up is a common mistake. `for...in` on an array gives you index strings ("0", "1", "2"), not the values.
</Warning>

For objects, you can also use `Object.entries()` which is often cleaner:

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };

for (const [key, value] of Object.entries(user)) {
  console.log(`${key}: ${value}`);
}
```

## Classic for loop

The traditional loop with a counter variable. Use it when you need precise control over the iteration:

```javascript theme={null}
for (let i = 0; i < 5; i++) {
  console.log(i);
}
// 0, 1, 2, 3, 4
```

Three parts: `for (initialization; condition; update)`

* **initialization**: `let i = 0` — runs once before the loop
* **condition**: `i < 5` — checked before each iteration
* **update**: `i++` — runs after each iteration

### Practical example

```javascript theme={null}
// Generate a grid of items
const rows = 3;
const cols = 4;

for (let row = 0; row < rows; row++) {
  for (let col = 0; col < cols; col++) {
    console.log(`Cell [${row}, ${col}]`);
  }
}
```

### Looping backwards

```javascript theme={null}
const items = ["first", "second", "third"];

for (let i = items.length - 1; i >= 0; i--) {
  console.log(items[i]);
}
// third, second, first
```

## while and do...while

For loops where you don't know the count in advance:

```javascript theme={null}
// while — checks condition first
let attempts = 0;
while (attempts < 3) {
  console.log(`Attempt ${attempts + 1}`);
  attempts++;
}

// do...while — runs at least once, checks condition after
let input;
do {
  input = getInput(); // Runs at least once
} while (!isValid(input));
```

<Info>
  `while` loops are uncommon in web development. You'll mostly use `for...of` for arrays and array methods like `.map()` and `.forEach()`. But `while` is useful for retry logic and polling patterns.
</Info>

## break and continue

Control the flow inside loops:

```javascript theme={null}
const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// break — exit the loop entirely
for (const num of numbers) {
  if (num > 5) break;
  console.log(num);
}
// 1, 2, 3, 4, 5

// continue — skip to the next iteration
for (const num of numbers) {
  if (num % 2 === 0) continue; // Skip even numbers
  console.log(num);
}
// 1, 3, 5, 7, 9
```

## Loops vs array methods

In modern JavaScript, you'll often choose between a loop and an array method. Here's when to use each:

| Task                           | Use                                          |
| ------------------------------ | -------------------------------------------- |
| Transform each item            | `.map()`                                     |
| Keep some items                | `.filter()`                                  |
| Find one item                  | `.find()`                                    |
| Check if something exists      | `.includes()` or `.some()`                   |
| Calculate a total              | `.reduce()`                                  |
| Side effects (log, DOM update) | `.forEach()` or `for...of`                   |
| Need `break`/`continue`        | `for...of` or `for`                          |
| Need the index                 | `.forEach()` or `for...of` with `.entries()` |

```javascript theme={null}
// Array method approach — usually preferred
const activeUsers = users.filter(u => u.active).map(u => u.name);

// Loop approach — needed for complex logic or early exit
const results = [];
for (const user of users) {
  if (user.role === "banned") continue;
  if (results.length >= 10) break;
  if (user.active) {
    results.push(user.name);
  }
}
```

<Tip>
  Prefer array methods when possible — they're more readable and less error-prone. Use `for...of` when you need `break`, `continue`, or complex multi-step logic inside the loop.
</Tip>

## What's next?

You've covered working with data — arrays, objects, destructuring, spread, JSON, conditionals, and loops. This is the toolbox you'll use in every web application.

Next up: asynchronous JavaScript. This is where things get interesting — you'll learn how JavaScript handles operations that take time, like fetching data from your FastAPI backend.

<Card title="Why async matters" icon="bolt" href="/async-apis/why-async-matters">
  Understand why JavaScript handles time differently
</Card>


# Objects
Source: https://js.maxbraglia.com/working-with-data/objects

Store data as key-value pairs with JavaScript objects

## What are objects?

Objects store data as key-value pairs. They represent *things* — a user, a product, an API response, a configuration. If arrays are ordered lists, objects are labeled containers.

```javascript theme={null}
const user = {
  name: "Sarah Chen",
  email: "sarah@example.com",
  age: 28,
  isAdmin: true,
};

console.log(user.name);  // "Sarah Chen"
console.log(user.email); // "sarah@example.com"
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    const user = {
      name: "Sarah",
      age: 28,
      role: "admin",
    };
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    user = {
        "name": "Sarah",
        "age": 28,
        "role": "admin",
    }
    ```
  </Tab>
</Tabs>

JavaScript objects are like Python dictionaries, but keys don't need quotes (unless they contain special characters or spaces).

## Accessing properties

Two ways to access object properties:

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };

// Dot notation — use when you know the property name
console.log(user.name); // "Sarah"
console.log(user.age);  // 28

// Bracket notation — use with variables or special characters
console.log(user["role"]); // "admin"

const field = "name";
console.log(user[field]); // "Sarah" — dynamic access
```

<Tip>
  Use dot notation by default — it's cleaner and easier to read. Use bracket notation when the property name is stored in a variable or contains characters like hyphens or spaces.
</Tip>

### Accessing nested properties

```javascript theme={null}
const order = {
  id: "ORD-001",
  customer: {
    name: "Sarah Chen",
    address: {
      city: "Portland",
      state: "OR",
    },
  },
  items: [
    { name: "Laptop", price: 999 },
    { name: "Mouse", price: 29 },
  ],
};

console.log(order.customer.name);           // "Sarah Chen"
console.log(order.customer.address.city);   // "Portland"
console.log(order.items[0].name);           // "Laptop"
console.log(order.items.length);            // 2
```

### Optional chaining

When you're not sure a nested property exists, use `?.` to avoid errors:

```javascript theme={null}
const user = { name: "Sarah", address: null };

// ❌ Without optional chaining — crashes
console.log(user.address.city); // TypeError: Cannot read properties of null

// ✅ With optional chaining — returns undefined
console.log(user.address?.city); // undefined
console.log(user.preferences?.theme); // undefined
```

<Warning>
  API responses often have missing or null fields. Use optional chaining `?.` whenever you access nested properties from external data. It prevents "Cannot read properties of undefined" — one of the most common JavaScript errors.
</Warning>

## Adding and updating properties

```javascript theme={null}
const user = { name: "Sarah", age: 28 };

// Update existing property
user.age = 29;

// Add new properties
user.email = "sarah@example.com";
user.role = "admin";

console.log(user);
// { name: "Sarah", age: 29, email: "sarah@example.com", role: "admin" }
```

```javascript theme={null}
// Delete a property
delete user.role;
console.log(user.role); // undefined
```

<Info>
  Remember: even though `user` is declared with `const`, you can still modify its properties. `const` prevents reassigning the variable itself (`user = something`), not modifying the object's contents. We covered this in the [Variables](/javascript-core/variables) lesson.
</Info>

## Checking if a property exists

```javascript theme={null}
const user = { name: "Sarah", email: "sarah@example.com", age: undefined };

// "in" operator — checks if the key exists (even if value is undefined)
console.log("name" in user);    // true
console.log("role" in user);    // false
console.log("age" in user);     // true (key exists, value is undefined)

// Comparing to undefined — can't distinguish "missing" from "set to undefined"
console.log(user.role !== undefined); // false
console.log(user.age !== undefined);  // false (misleading!)
```

<Tip>
  Use the `in` operator when you need to know if a key exists, regardless of its value. Use direct comparison when you just care about whether the value is usable.
</Tip>

## Iterating over objects

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };

// Get all keys
console.log(Object.keys(user));   // ["name", "age", "role"]

// Get all values
console.log(Object.values(user)); // ["Sarah", 28, "admin"]

// Get key-value pairs
console.log(Object.entries(user)); // [["name", "Sarah"], ["age", 28], ["role", "admin"]]

// Loop through entries
for (const [key, value] of Object.entries(user)) {
  console.log(`${key}: ${value}`);
}
// name: Sarah
// age: 28
// role: admin
```

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    for (const [key, value] of Object.entries(user)) {
      console.log(`${key}: ${value}`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    for key, value in user.items():
        print(f"{key}: {value}")
    ```
  </Tab>
</Tabs>

`Object.entries()` is JavaScript's equivalent of Python's `.items()`.

## Shorthand property names

When a variable name matches the property name, you can use a shorthand:

```javascript theme={null}
const name = "Sarah";
const age = 28;
const role = "admin";

// ❌ Long form
const user = { name: name, age: age, role: role };

// ✅ Shorthand — same result
const user = { name, age, role };

console.log(user); // { name: "Sarah", age: 28, role: "admin" }
```

You'll see this pattern everywhere — especially when returning data from functions or building objects from variables.

## Methods (functions on objects)

Objects can contain functions. When a function is on an object, it's called a method:

```javascript theme={null}
const calculator = {
  add(a, b) {
    return a + b;
  },
  subtract(a, b) {
    return a - b;
  },
  multiply(a, b) {
    return a * b;
  },
};

console.log(calculator.add(5, 3));      // 8
console.log(calculator.multiply(4, 7)); // 28
```

<Info>
  In this course, you won't write many object methods yourself. React components use functions and hooks instead. But you'll see methods on built-in objects (`Math.round()`, `JSON.parse()`, `console.log()`) and on API response objects.
</Info>

## What's next?

You can create and work with objects. Now let's learn destructuring — a cleaner way to extract values from objects and arrays.

<Card title="Destructuring" icon="scissors" href="/working-with-data/destructuring">
  Extract values into individual variables
</Card>


# Spread operator
Source: https://js.maxbraglia.com/working-with-data/spread-operator

Copy, merge, and expand arrays and objects with the spread syntax

## What is the spread operator?

The spread operator `...` expands an array or object into its individual elements. It's how you copy, merge, and build new data structures without mutating the originals.

```javascript theme={null}
const numbers = [1, 2, 3];
const moreNumbers = [...numbers, 4, 5, 6];

console.log(moreNumbers); // [1, 2, 3, 4, 5, 6]
console.log(numbers);     // [1, 2, 3] — original unchanged
```

You'll use the spread operator constantly in React, where you need to create new arrays and objects instead of mutating state.

## Array spreading

### Copying an array

```javascript theme={null}
const original = [1, 2, 3];
const copy = [...original];

copy.push(4);
console.log(original); // [1, 2, 3] — unaffected
console.log(copy);     // [1, 2, 3, 4]
```

<Info>
  Python mental model: `copy = [...original]` is like `copy = [*original]` or `copy = original.copy()`. In all cases, this is a **shallow** copy.
</Info>

### Merging arrays

```javascript theme={null}
const frontend = ["React", "Vue", "Angular"];
const backend = ["Node", "Django", "FastAPI"];

const allFrameworks = [...frontend, ...backend];
console.log(allFrameworks);
// ["React", "Vue", "Angular", "Node", "Django", "FastAPI"]
```

### Adding items without mutation

```javascript theme={null}
const colors = ["red", "green", "blue"];

// Add to the end
const withYellow = [...colors, "yellow"];
// ["red", "green", "blue", "yellow"]

// Add to the beginning
const withWhite = ["white", ...colors];
// ["white", "red", "green", "blue"]

// Insert in the middle
const withOrange = [...colors.slice(0, 2), "orange", ...colors.slice(2)];
// ["red", "green", "orange", "blue"]
```

<Tip>
  In React, never use `.push()` or `.pop()` on state arrays. Instead, use spread to create new arrays: `setItems([...items, newItem])`. This tells React that the data changed and it needs to re-render.
</Tip>

## Object spreading

### Copying an object

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };
const copy = { ...user };

copy.age = 29;
console.log(user.age); // 28 — original unchanged
console.log(copy.age); // 29
```

### Merging objects

```javascript theme={null}
const defaults = { theme: "light", language: "en", fontSize: 14 };
const userPrefs = { theme: "dark", fontSize: 16 };

const settings = { ...defaults, ...userPrefs };
console.log(settings);
// { theme: "dark", language: "en", fontSize: 16 }
```

Properties from later objects override earlier ones. `userPrefs.theme` ("dark") overrides `defaults.theme` ("light").

### Updating a property without mutation

```javascript theme={null}
const user = { name: "Sarah", age: 28, role: "admin" };

// Create a new object with one property changed
const updatedUser = { ...user, age: 29 };

console.log(user);        // { name: "Sarah", age: 28, role: "admin" }
console.log(updatedUser); // { name: "Sarah", age: 29, role: "admin" }
```

This is the pattern you'll use in React state updates:

```jsx theme={null}
const [user, setUser] = useState({ name: "Sarah", age: 28 });

// Update age without mutating
setUser({ ...user, age: 29 });
```

<Warning>
  Spread creates a **shallow copy**. If your object contains nested objects, the inner objects are still shared references. For deep nested updates, spread each level: `{ ...user, address: { ...user.address, city: "Seattle" } }`.
</Warning>

<Tip>
  Python mental model: this is the same behavior as `dict.copy()` or `{**user}` — nested dicts/lists are still shared unless you copy those nested levels too.
</Tip>

## Practical patterns

### Building API request bodies

```javascript theme={null}
function createUserPayload(formData) {
  return {
    ...formData,
    createdAt: new Date().toISOString(),
    status: "active",
  };
}

const payload = createUserPayload({ name: "Sarah", email: "sarah@example.com" });
// { name: "Sarah", email: "sarah@example.com", createdAt: "2024-01-15T...", status: "active" }
```

### Removing a property (rest + spread)

```javascript theme={null}
const user = { name: "Sarah", password: "secret123", role: "admin" };

// Remove password, keep everything else
const { password, ...safeUser } = user;
console.log(safeUser); // { name: "Sarah", role: "admin" }
```

This combines destructuring (to grab `password`) with rest syntax (`...safeUser` to collect everything else). It's a clean way to strip sensitive fields.

### Conditional properties

```javascript theme={null}
const isAdmin = true;

const user = {
  name: "Sarah",
  email: "sarah@example.com",
  ...(isAdmin && { role: "admin", permissions: ["read", "write", "delete"] }),
};

console.log(user);
// { name: "Sarah", email: "sarah@example.com", role: "admin", permissions: [...] }
```

<Info>
  The `...(condition && { props })` pattern conditionally includes properties. If the condition is false, `false` is spread (which adds nothing). You'll see this when building request bodies with optional fields.
</Info>

<Tip>
  Python mental model: this is similar to `{**base, **({"role": "admin"} if is_admin else {})}`.
</Tip>

## Comparing to Python

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    // Spread arrays
    const combined = [...arr1, ...arr2];

    // Spread objects
    const merged = { ...obj1, ...obj2 };

    // Copy + update
    const updated = { ...user, age: 29 };
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Unpack lists
    combined = [*list1, *list2]

    # Merge dicts (3.9+)
    merged = {**dict1, **dict2}
    # or: merged = dict1 | dict2

    # Copy + update
    updated = {**user, "age": 29}
    ```
  </Tab>
</Tabs>

JavaScript's `...` is like Python's `*` for lists and `**` for dicts. Same concept, same patterns.

## What's next?

You can work with arrays and objects. Now let's learn about JSON — the format your frontend and backend use to exchange data.

<Card title="JSON basics" icon="brackets-curly" href="/working-with-data/json-basics">
  Convert between JSON strings and JavaScript objects
</Card>