### Install Dependencies

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using npm.

```bash
npm install
```

--------------------------------

### Manual Render Flushing with `setupRerender`

Source: https://context7.com/tanstack/preact/llms.txt

Use `setupRerender` to get a `rerender` function for manually flushing queued Preact re-renders, providing precise control over state updates during tests.

```jsx
import { render } from 'preact';
import { setupRerender } from 'preact/test-utils';
import { useState } from 'preact/hooks';

function Input() {
  const [value, setValue] = useState('');
  return <input value={value} onInput={e => setValue(e.currentTarget.value)} />;
}

const rerender = setupRerender();
const container = document.createElement('div');

render(<Input />, container);

const input = container.querySelector('input');
input.value = 'hello';
input.dispatchEvent(new Event('input'));

// Without calling rerender(), the DOM still shows the old value.
// Calling rerender() flushes all queued updates:
rerender();

console.log(input.value); // "hello"
```

--------------------------------

### Initializing and Updating Git Submodules for Benchmarks

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Commands to initialize, update, and manage git submodules, specifically for the benchmarks repository. Ensure PNPM is installed before running.

```bash
pnpm -v # Make sure pnpm is installed
git submodule update --init --recursive
cd benchmarks
pnpm i
```

```bash
# In the benchmarks folder
pnpm run bench
```

```bash
git submodule update --recursive
```

```bash
git checkout --recurse-submodules
```

--------------------------------

### Example Usage of Automatic JSX Transform

Source: https://context7.com/tanstack/preact/llms.txt

Demonstrates a component using JSX with the automatic transform, eliminating the need for manual `h` imports.

```jsx
// No need for: import { h } from 'preact'
// Babel/TS automatically imports jsx/jsxs from 'preact/jsx-runtime'

function App() {
  return (
    <main>
      <h1>Automatic JSX Transform</h1>
      <p>No manual h() import needed!</p>
    </main>
  );
}

export default App;
```

--------------------------------

### Preact Repository Structure Overview

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

This bash script provides a visual overview of the Preact repository structure, highlighting core, addons, and demo directories.

```bash
# The repo root (folder where you cloned the repo into)
/
  src/  # Source code of our core
  test/ # Unit tests for core
  dist/ # Build artifacts for publishing on npm (may not be present)

  # Sub-package, can be imported via `preact/compat` by users.
  # Compat stands for react-compatibility layer which tries to mirror the
  # react API as close as possible (mostly legacy APIs)
  compat/
  	src/  # Source code of the compat addon
  	test/ # Tests related to the compat addon
  	dist/ # Build artifacts for publishing on npm (may not be present)

  # Sub-package, can be imported via `preact/hooks` by users.
  # The hooks API is an effect based API to deal with component lifecycles.
  # It's similar to hooks in React
  hooks/
  	src/  # Source code of the hooks addon
  	test/ # Tests related to the hooks addon
  	dist/ # Build artifacts for publishing on npm (may not be present)

  # Sub-package, can be imported via `preact/debug` by users.
  # Includes debugging warnings and error messages for common mistakes found
  # in Preact applications. Also hosts the devtools bridge
  debug/
  	src/  # Source code of the debug addon
  	test/ # Tests related to the debug addon
  	dist/ # Build artifacts for publishing on npm (may not be present)

  # Sub-package, can be imported via `preact/test-utils` by users.
  # Provides helpers to make testing Preact applications easier
  test-utils/
  	src/  # Source code of the test-utils addon
  	test/ # Tests related to the test-utils addon
  	dist/ # Build artifacts for publishing on npm (may not be present)

  # A demo application that we use to debug tricky errors and play with new
  # features.
  demo/

  # Contains build scripts and dependencies for development
  package.json
```

--------------------------------

### Navigate to Preact Directory

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Change your current directory to the cloned Preact repository folder.

```bash
cd preact/
```

--------------------------------

### setupRerender()

Source: https://context7.com/tanstack/preact/llms.txt

Manually control render flushing in tests. Returns a rerender function to manually flush queued Preact re-renders, giving precise control over when state updates are applied during tests.

```APIDOC
## setupRerender()

### Description
Manually control render flushing in tests. Returns a `rerender` function to manually flush queued Preact re-renders, giving precise control over when state updates are applied during tests.

### Usage
```jsx
import { render } from 'preact';
import { setupRerender } from 'preact/test-utils';
import { useState } from 'preact/hooks';

function Input() {
  const [value, setValue] = useState('');
  return <input value={value} onInput={e => setValue(e.currentTarget.value)} />;
}

const rerender = setupRerender();
const container = document.createElement('div');

render(<Input />, container);

const input = container.querySelector('input');
input.value = 'hello';
input.dispatchEvent(new Event('input'));

// Without calling rerender(), the DOM still shows the old value.
// Calling rerender() flushes all queued updates:
rerender();

console.log(input.value); // "hello"
```
```

--------------------------------

### Render and Update UI with Preact

Source: https://github.com/tanstack/preact/blob/main/README.md

Use the `render` function to create a UI tree and append it to a DOM element. Subsequent calls to `render` with the same element will update the UI efficiently.

```javascript
import { h, render } from 'preact';
// Tells babel to use h for JSX. It's better to configure this globally.
// See https://babeljs.io/docs/en/babel-plugin-transform-react-jsx#usage
// In tsconfig you can specify this with the jsxFactory
/** @jsx h */

// create our tree and append it to document.body:
render(
	<main>
		<h1>Hello</h1>
	</main>,
	document.body
);

// update the tree in-place:
render(
	<main>
		<h1>Hello World!</h1>
	</main>,
	document.body
);
// ^ this second invocation of render(...) will use a single DOM call to update the text of the <h1>
```

--------------------------------

### Release Note Title Format

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Follow this format for release note titles. The version name is optional.

```txt
Version Name
```

```txt
10.0.0-beta.1 Los Compresseros
```

--------------------------------

### options

Source: https://context7.com/tanstack/preact/llms.txt

A global options object that allows libraries to hook into Preact's rendering pipeline for custom lifecycle hooks.

```APIDOC
## options — Global lifecycle hooks for Preact internals

A global options object that allows libraries (devtools, hooks, compat) to hook into Preact's rendering pipeline.

```js
import { options } from 'preact';

// Called every time a VNode is created
const prevVnode = options.vnode;
options.vnode = vnode => {
  if (prevVnode) prevVnode(vnode);
  console.log('VNode created:', vnode.type);
};

// Custom async rendering scheduler (e.g., replace with requestIdleCallback)
options.debounceRendering = cb => {
  requestIdleCallback(cb, { timeout: 100 });
};

// Intercept events before they reach handlers
options.event = e => {
  console.log('Event intercepted:', e.type);
  return e;
};
```
```

--------------------------------

### Clone Preact Repository

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Use this command to clone the Preact git repository to your local machine.

```bash
git clone git@github.com:preactjs/preact.git
```

--------------------------------

### createContext

Source: https://context7.com/tanstack/preact/llms.txt

Creates a Context object that allows components to subscribe to context value changes, enabling prop drilling avoidance.

```APIDOC
## createContext(defaultValue) — Create a context for prop drilling avoidance

Creates a Context object with a Provider and Consumer. Any component in the tree can subscribe to context value changes.

```jsx
import { createContext, render } from 'preact';
import { useContext } from 'preact/hooks';

const ThemeContext = createContext('light');

function ThemedButton() {
  const theme = useContext(ThemeContext);
  return <button class={`btn-${theme}`}>Themed Button</button>;
}

function App() {
  return (
    <ThemeContext.Provider value="dark">
      <ThemedButton />
      {/* Consumer render prop pattern */}
      <ThemeContext.Consumer>
        {theme => <p>Current theme: {theme}</p>}
      </ThemeContext.Consumer>
    </ThemeContext.Provider>
  );
}

render(<App />, document.getElementById('app'));
// ThemedButton renders with class="btn-dark"
```
```

--------------------------------

### Code-split components with Suspense and lazy

Source: https://context7.com/tanstack/preact/llms.txt

Utilize Suspense and lazy for asynchronous component loading. lazy wraps dynamic imports, and Suspense displays a fallback UI while the component is being fetched. Ensure components are imported from 'preact/compat'.

```jsx
import { render } from 'preact';
import { Suspense, lazy } from 'preact/compat';

// Dynamically imported — loaded only when needed
const HeavyChart = lazy(() => import('./components/HeavyChart'));
const AdminPanel = lazy(() => import('./components/AdminPanel'));

function Dashboard({ showAdmin }) {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<div class="spinner">Loading chart…</div>}>
        <HeavyChart data={[10, 20, 30]} />
      </Suspense>

      {showAdmin && (
        <Suspense fallback={<p>Loading admin panel…</p>}>
          <AdminPanel />
        </Suspense>
      )}
    </div>
  );
}

render(<Dashboard showAdmin={true} />, document.getElementById('app'));
```

--------------------------------

### Fragment

Source: https://context7.com/tanstack/preact/llms.txt

Renders multiple children without introducing an extra DOM element.

```APIDOC
## Fragment

### Description
Renders multiple children without introducing an extra DOM element.

### Request Example
```jsx
import { Fragment, render, h } from 'preact';

function TableRows() {
  return (
    h(Fragment, null,
      h('tr', null, h('td', null, 'Row 1, Col 1'), h('td', null, 'Row 1, Col 2')),
      h('tr', null, h('td', null, 'Row 2, Col 1'), h('td', null, 'Row 2, Col 2'))
    )
  );
  // Shorthand: <>
}

render(
  h('table', null, h('tbody', null, h(TableRows))),
  document.getElementById('app')
);
```
```

--------------------------------

### memo

Source: https://context7.com/tanstack/preact/llms.txt

Wraps a functional component and performs a shallow prop comparison (or custom comparison) before deciding to re-render, optimizing performance by skipping unnecessary re-renders.

```APIDOC
## Compat API (`preact/compat`)

### `memo(component, comparer?)` — Skip re-renders when props are unchanged

Wraps a functional component and performs a shallow prop comparison (or custom comparison) before deciding to re-render.

```jsx
import { render } from 'preact';
import { useState } from 'preact/hooks';
import { memo } from 'preact/compat';

const UserCard = memo(
  function UserCard({ user }) {
    console.log('UserCard rendered:', user.name);
    return <div>{user.name} — {user.email}</div>;
  },
  // Optional custom comparer — skip re-render if only `updatedAt` changed
  (prev, next) => prev.user.id === next.user.id && prev.user.email === next.user.email
);

function App() {
  const [tick, setTick] = useState(0);
  const user = { id: 1, name: 'Alice', email: 'alice@example.com' };

  return (
    <div>
      <UserCard user={user} />
      <button onClick={() => setTick(t => t + 1)}>Re-render Parent ({tick})</button>
      {/* UserCard does NOT re-render when tick changes */}
    </div>
  );
}

render(<App />, document.getElementById('app'));
```
```

--------------------------------

### Create Context with createContext

Source: https://context7.com/tanstack/preact/llms.txt

Use createContext to create a context object that allows components to subscribe to context value changes, avoiding prop drilling. The returned object includes a Provider and Consumer.

```jsx
import { createContext, render } from 'preact';
import { useContext } from 'preact/hooks';

const ThemeContext = createContext('light');

function ThemedButton() {
  const theme = useContext(ThemeContext);
  return <button class={`btn-${theme}`}>Themed Button</button>;
}

function App() {
  return (
    <ThemeContext.Provider value="dark">
      <ThemedButton />
      {/* Consumer render prop pattern */}
      <ThemeContext.Consumer>
        {theme => <p>Current theme: {theme}</p>}
      </ThemeContext.Consumer>
    </ThemeContext.Provider>
  );
}

render(<App />, document.getElementById('app'));
// ThemedButton renders with class="btn-dark"
```

--------------------------------

### Memoize Expensive Computations with useMemo

Source: https://context7.com/tanstack/preact/llms.txt

Use useMemo to recompute a value only when its dependencies change. This avoids unnecessary recalculations on every render, improving performance for costly operations.

```jsx
import { render } from 'preact';
import { useState, useMemo } from 'preact/hooks';

function PrimeList({ limit }) {
  const primes = useMemo(() => {
    console.log('Computing primes up to', limit); // Only recalculates when limit changes
    const result = [];
    for (let n = 2; n <= limit; n++) {
      if (!result.some(p => n % p === 0)) result.push(n);
    }
    return result;
  }, [limit]);

  return <p>Found {primes.length} primes up to {limit}: {primes.slice(0, 10).join(', ')}…</p>;
}

function App() {
  const [limit, setLimit] = useState(100);
  return (
    <>
      <input type="number" value={limit} onInput={e => setLimit(+e.currentTarget.value)} />
      <PrimeList limit={limit} />
    </>
  );
}

render(<App />, document.getElementById('app'));
```

--------------------------------

### Suspense and lazy

Source: https://context7.com/tanstack/preact/llms.txt

Enables code-splitting components with asynchronous loading. `lazy` wraps a dynamic import, and `Suspense` renders a fallback UI while the lazily loaded component is being fetched.

```APIDOC
## `Suspense` and `lazy` — Code-split components with async loading

`lazy` wraps a dynamic import and returns a component that integrates with `Suspense`. While the component loads, `Suspense` renders its `fallback`.

### Example
```jsx
import { render } from 'preact';
import { Suspense, lazy } from 'preact/compat';

// Dynamically imported — loaded only when needed
const HeavyChart = lazy(() => import('./components/HeavyChart'));
const AdminPanel = lazy(() => import('./components/AdminPanel'));

function Dashboard({ showAdmin }) {
  return (
    <div>
      <h1>Dashboard</h1>
      <Suspense fallback={<div class="spinner">Loading chart…</div>}>
        <HeavyChart data={[10, 20, 30]} />
      </Suspense>

      {showAdmin && (
        <Suspense fallback={<p>Loading admin panel…</p>}>
          <AdminPanel />
        </Suspense>
      )}
    </div>
  );
}

render(<Dashboard showAdmin={true} />, document.getElementById('app'));
```
```

--------------------------------

### createElement(type, props, ...children) / h(type, props, ...children)

Source: https://context7.com/tanstack/preact/llms.txt

Creates and returns a VNode. This is the function that JSX compiles to. Both `createElement` and `h` are aliases.

```APIDOC
## createElement(type, props, ...children) / h(type, props, ...children)

### Description
Creates and returns a VNode. This is the function that JSX compiles to. Both `createElement` and `h` are aliases.

### Parameters
#### Path Parameters
- **type** (string | Component) - Required - The element type or component.
- **props** (object) - Optional - The properties for the VNode.
- **children** (...any) - Optional - The children of the VNode.

### Request Example
```jsx
import { h, createElement } from 'preact';

// Using JSX (compiles to h() calls)
const vnode = h('div', { class: 'greeting' }, 'Hello ', h('span', null, 'World'));

// Equivalent without JSX
const vnode2 = createElement('div', { class: 'greeting' },
  'Hello ',
  createElement('span', null, 'World')
);

// With a component type
function Greeting({ name }) {
  return h('p', null, `Hello, ${name}`);
}
const vnode3 = createElement(Greeting, { name: 'Preact' });
```
```

--------------------------------

### hydrate(vnode, container)

Source: https://context7.com/tanstack/preact/llms.txt

Attaches Preact to existing server-rendered HTML without re-creating DOM nodes, making hydration efficient for SSR use cases.

```APIDOC
## hydrate(vnode, container)

### Description
Attaches Preact to existing server-rendered HTML without re-creating DOM nodes, making hydration efficient for SSR use cases.

### Parameters
#### Path Parameters
- **vnode** (VNode) - Required - The virtual DOM node to hydrate.
- **container** (DOMElement) - Required - The DOM element containing server-rendered HTML.

### Request Example
```jsx
import { hydrate, h } from 'preact';

// HTML already in the document from the server:
// <div id="app"><h1>Hello SSR</h1></div>

hyydrate(h(App), document.getElementById('app'));
// Preact walks existing DOM nodes and attaches event listeners without re-rendering
```
```

--------------------------------

### Configure Automatic JSX Transform with Babel

Source: https://context7.com/tanstack/preact/llms.txt

Configure Babel to use Preact's automatic JSX runtime for JSX without manual `h` imports.

```javascript
// babel.config.js
module.exports = {
  plugins: [
    ['@babel/plugin-transform-react-jsx', {
      runtime: 'automatic',
      importSource: 'preact'
    }]
  ]
};
```

--------------------------------

### Create a Component with State in Preact

Source: https://github.com/tanstack/preact/blob/main/README.md

Define functional components using hooks like `useState` to manage component state. This allows for dynamic and interactive user interfaces.

```javascript
import { render, h } from 'preact';
import { useState } from 'preact/hooks';

/** @jsx h */

const App = () => {
	const [input, setInput] = useState('');

	return (
		<div>
			<p>Do you agree to the statement: "Preact is awesome"?</p>
			<input value={input} onInput={e => setInput(e.target.value)} />
		</div>
	);
};

render(<App />, document.body);
```

--------------------------------

### Hydrate Server-Rendered HTML with Preact

Source: https://context7.com/tanstack/preact/llms.txt

Use `hydrate` to attach Preact to existing server-rendered HTML without re-creating DOM nodes. This is efficient for SSR use cases.

```jsx
import { hydrate } from 'preact';

// HTML already in the document from the server:
// <div id="app"><h1>Hello SSR</h1></div>

hydrate(<App />, document.getElementById('app'));
// Preact walks existing DOM nodes and attaches event listeners without re-rendering
```

--------------------------------

### Mount, Update, and Unmount a Preact Tree

Source: https://context7.com/tanstack/preact/llms.txt

Use `render` to mount a Preact component tree into a DOM element. Subsequent calls with the same container update the tree efficiently. Pass `null` to unmount.

```jsx
import { render, h } from 'preact';

// First render — mounts the app
render(<h1>Hello, World!</h1>, document.getElementById('app'));

// Second render on the same container — diffs and patches only the changed parts
render(<h1>Hello, Preact!</h1>, document.getElementById('app'));

// Unmount
render(null, document.getElementById('app'));
```

--------------------------------

### useId

Source: https://context7.com/tanstack/preact/llms.txt

Generates a stable, unique ID for accessibility purposes, ensuring consistency between server and client renders.

```APIDOC
## `useId()` — Generate a stable unique ID

Generates a stable, unique ID for accessibility purposes (linking `<label>` to `<input>`, etc.). IDs are consistent between server and client renders.

```jsx
import { render } from 'preact';
import { useId } from 'preact/hooks';

function LabeledInput({ label, type = 'text' }) {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>{label}</label>
      <input id={id} type={type} />
    </div>
  );
}

function Form() {
  return (
    <form>
      <LabeledInput label="Email" type="email" />
      <LabeledInput label="Password" type="password" />
      {/* Each instance gets a unique, stable id like "P0-0", "P0-1" */}
    </form>
  );
}

render(<Form />, document.getElementById('app'));
```
```

--------------------------------

### render(vnode, container)

Source: https://context7.com/tanstack/preact/llms.txt

Renders a Virtual DOM tree into the given container DOM node. Subsequent calls on the same container perform diff-updates. Pass `null` to unmount the tree.

```APIDOC
## render(vnode, container)

### Description
Renders a Virtual DOM tree into the given container DOM node. Calling `render` a second time on the same container performs an in-place diff-update. Pass `null` to unmount the tree.

### Parameters
#### Path Parameters
- **vnode** (VNode) - Required - The virtual DOM node to render.
- **container** (DOMElement) - Required - The DOM element to render into.

### Request Example
```jsx
import { render, h } from 'preact';

// First render — mounts the app
render(h('h1', null, 'Hello, World!'), document.getElementById('app'));

// Second render on the same container — diffs and patches only the changed parts
render(h('h1', null, 'Hello, Preact!'), document.getElementById('app'));

// Unmount
render(null, document.getElementById('app'));
```
```

--------------------------------

### Running Individual Tests with .only

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Append `.only` to an `it` block to execute a single test. This is useful for focused debugging.

```jsx
it.only('should test something', () => {
	expect(1).to.equal(1);
});
```

--------------------------------

### createRef

Source: https://context7.com/tanstack/preact/llms.txt

Returns a mutable ref object that persists for the full component lifetime, attachable to DOM elements or components via the `ref` prop.

```APIDOC
## createRef() — Create a mutable ref object

Returns a `{ current: null }` object that persists for the full component lifetime. Attach to DOM elements or components via the `ref` prop.

```jsx
import { createRef, Component, render } from 'preact';

class TextInput extends Component {
  inputRef = createRef();

  focusInput = () => {
    this.inputRef.current.focus();
    console.log('Input value:', this.inputRef.current.value);
  };

  render() {
    return (
      <div>
        <input ref={this.inputRef} type="text" placeholder="Type here..." />
        <button onClick={this.focusInput}>Focus</button>
      </div>
    );
  }
}

render(<TextInput />, document.getElementById('app'));
```
```

--------------------------------

### Generate Changelog with changelogged CLI

Source: https://github.com/tanstack/preact/blob/main/CONTRIBUTING.md

Use the changelogged CLI tool to generate changelogs by specifying a range of tags. This command is similar to git diff.

```bash
changelogged 10.0.0-rc.2..HEAD
```

--------------------------------

### Create Virtual DOM Nodes with `h` or `createElement`

Source: https://context7.com/tanstack/preact/llms.txt

Use `h` or `createElement` to create Virtual DOM nodes, which is what JSX compiles to. These functions accept the element type, props, and children.

```jsx
import { h, createElement } from 'preact';

// Using JSX (compiles to h() calls)
const vnode = <div class="greeting">Hello <span>World</span></div>;

// Equivalent without JSX
const vnode2 = h('div', { class: 'greeting' },
  'Hello ',
  h('span', null, 'World')
);

// With a component type
function Greeting({ name }) {
  return h('p', null, `Hello, ${name}!`);
}
const vnode3 = createElement(Greeting, { name: 'Preact' });
```

--------------------------------

### flushSync

Source: https://context7.com/tanstack/preact/llms.txt

Forces synchronous state updates. Any state updates within the provided callback function are applied immediately before `flushSync` returns. This is useful when DOM measurements are needed right after a state change.

```APIDOC
## `flushSync(fn)` — Force synchronous state updates

Wraps a state update in `flushSync` to ensure Preact applies it synchronously before returning. Useful when you need to read DOM state immediately after an update.

### Parameters
- **fn**: A function containing the state update(s) to be flushed synchronously.

### Example
```jsx
import { render } from 'preact';
import { useState, useRef } from 'preact/hooks';
import { flushSync } from 'preact/compat';

function LiveList() {
  const [items, setItems] = useState(['Apple', 'Banana']);
  const listRef = useRef(null);

  const addItem = () => {
    flushSync(() => {
      setItems(prev => [...prev, `Item ${prev.length + 1}`]);
    });
    // DOM is updated synchronously here — safe to read layout
    const list = listRef.current;
    list.scrollTop = list.scrollHeight; // Scroll to bottom immediately
  };

  return (
    <div>
      <ul ref={listRef} style={{ height: '100px', overflowY: 'scroll' }}>
        {items.map((item, i) => <li key={i}>{item}</li>)}
      </ul>
      <button onClick={addItem}>Add Item</button>
    </div>
  );
}

render(<LiveList />, document.getElementById('app'));
```
```

--------------------------------

### Configure Automatic JSX Transform with TypeScript

Source: https://context7.com/tanstack/preact/llms.txt

Configure TypeScript to use Preact's automatic JSX runtime for JSX without manual `h` imports.

```json
// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}
```

--------------------------------

### createPortal

Source: https://context7.com/tanstack/preact/llms.txt

Renders children into a different part of the DOM, outside the parent's hierarchy, while maintaining context within the Preact component tree. This is useful for elements like modals or tooltips that need to be rendered at a different location in the DOM.

```APIDOC
## `createPortal(vnode, container)` — Render children outside the parent DOM hierarchy

Renders a component into a different part of the DOM (e.g., modals, tooltips, notifications appended to `document.body`), while keeping it in the Preact component tree for context and event propagation.

### Parameters
- **vnode**: The Preact virtual DOM node to render.
- **container**: The DOM node where the `vnode` should be rendered.

### Example
```jsx
import { render } from 'preact';
import { useState } from 'preact/hooks';
import { createPortal } from 'preact/compat';

function Modal({ children, onClose }) {
  return createPortal(
    <div class="modal-overlay" onClick={onClose}>
      <div class="modal-content" onClick={e => e.stopPropagation()}>
        {children}
        <button onClick={onClose}>Close</button>
      </div>
    </div>,
    document.body  // Rendered at document.body level, outside #app
  );
}

function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div id="app-root">
      <button onClick={() => setShowModal(true)}>Open Modal</button>
      {showModal && (
        <Modal onClose={() => setShowModal(false)}>
          <h2>Modal Content</h2>
          <p>This is rendered directly into document.body.</p>
        </Modal>
      )}
    </div>
  );
}

render(<App />, document.getElementById('app'));
```
```

--------------------------------

### Component

Source: https://context7.com/tanstack/preact/llms.txt

Base class for class components. Extend `Component` to create stateful class components with lifecycle methods. Provides `setState()` and `forceUpdate()`.

```APIDOC
## Component

### Description
Base class for class components. Extend `Component` to create stateful class components with lifecycle methods. Provides `setState()` and `forceUpdate()`.

### Methods
- **setState(updater, callback)**: Updates the component's state and re-renders.
- **forceUpdate(callback)**: Forces a re-render of the component.

### Lifecycle Methods
- **componentDidMount()**: Called after the component is mounted.
- **componentDidUpdate(prevProps, prevState)**: Called after the component updates.
- **componentWillUnmount()**: Called before the component is unmounted.

### Request Example
```jsx
import { Component, render, h } from 'preact';

class Counter extends Component {
  constructor(props) {
    super(props);
    this.state = { count: 0 };
  }

  componentDidMount() {
    console.log('Counter mounted');
  }

  componentDidUpdate(prevProps, prevState) {
    if (prevState.count !== this.state.count) {
      console.log(`Count changed to ${this.state.count}`);
    }
  }

  componentWillUnmount() {
    console.log('Counter unmounted');
  }

  increment = () => {
    // Functional updater to safely build on previous state
    this.setState(prev => ({ count: prev.count + 1 }), () => {
      console.log('State updated, callback fired');
    });
  };

  render() {
    return (
      h('div', null,
        h('p', null, `Count: ${this.state.count}`),
        h('button', { onClick: this.increment }, '+1'),
        h('button', { onClick: () => this.forceUpdate() }, 'Force Re-render')
      )
    );
  }
}

render(h(Counter), document.getElementById('app'));
```
```

--------------------------------

### Memoize Callback Functions with useCallback

Source: https://context7.com/tanstack/preact/llms.txt

Employ useCallback to return a stable function reference that only changes when its dependencies change. This is crucial for preventing unnecessary re-renders in child components that rely on referential equality.

```jsx
import { render } from 'preact';
import { useState, useCallback, memo } from 'preact/hooks';

const ExpensiveChild = memo(function ExpensiveChild({ onClick, label }) {
  console.log('ExpensiveChild rendered:', label);
  return <button onClick={onClick}>{label}</button>;
});

function Parent() {
  const [count, setCount] = useState(0);
  const [other, setOther] = useState(0);

  // Stable reference — ExpensiveChild won't re-render when `other` changes
  const handleClick = useCallback(() => {
    setCount(c => c + 1);
  }, []); // No deps → created once

  return (
    <div>
      <p>Count: {count}, Other: {other}</p>
      <ExpensiveChild onClick={handleClick} label="Increment Count" />
      <button onClick={() => setOther(o => o + 1)}>Change Other</button>
    </div>
  );
}

render(<Parent />, document.getElementById('app'));
```

--------------------------------

### Stateful Class Components with `Component`

Source: https://context7.com/tanstack/preact/llms.txt

Extend `Component` to create stateful class components. Use `setState()` for state updates and `forceUpdate()` to re-render. Lifecycle methods like `componentDidMount` and `componentDidUpdate` are available.

```jsx
import { Component, render } from 'preact';

class Counter extends Component {
  constructor(props) {
    super(props);
    this.state = { count: 0 };
  }

  componentDidMount() {
    console.log('Counter mounted');
  }

  componentDidUpdate(prevProps, prevState) {
    if (prevState.count !== this.state.count) {
      console.log(`Count changed to ${this.state.count}`);
    }
  }

  componentWillUnmount() {
    console.log('Counter unmounted');
  }

  increment = () => {
    // Functional updater to safely build on previous state
    this.setState(prev => ({ count: prev.count + 1 }), () => {
      console.log('State updated, callback fired');
    });
  };

  render() {
    return (
      <div>
        <p>Count: {this.state.count}</p>
        <button onClick={this.increment}>+1</button>
        <button onClick={() => this.forceUpdate()}>Force Re-render</button>
      </div>
    );
  }
}

render(<Counter />, document.getElementById('app'));
```

--------------------------------

### useState

Source: https://context7.com/tanstack/preact/llms.txt

A hook that returns a stateful value and a setter function, enabling local component state management.

```APIDOC
## useState(initialState) — Local component state

Returns a stateful value and a setter function. The setter accepts a new value or a function that receives the previous state.

```jsx
import { render } from 'preact';
import { useState } from 'preact/hooks';

function Counter() {
  const [count, setCount] = useState(0);
  const [name, setName] = useState(() => localStorage.getItem('name') || 'Guest');

  return (
    <div>
      <p>Hello, {name}! Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
      <button onClick={() => setCount(0)}>Reset</button>
      <input
        value={name}
        onInput={e => setName(e.currentTarget.value)}
        placeholder="Your name"
      />
    </div>
  );
}

render(<Counter />, document.getElementById('app'));
```
```

--------------------------------

### Memoize Components with memo in Preact Compat

Source: https://context7.com/tanstack/preact/llms.txt

Wraps a functional component to skip re-renders when props are unchanged, using shallow prop comparison or a custom comparer function. This is useful for performance optimization.

```jsx
import { render } from 'preact';
import { useState } from 'preact/hooks';
import { memo } from 'preact/compat';

const UserCard = memo(
  function UserCard({ user }) {
    console.log('UserCard rendered:', user.name);
    return <div>{user.name} — {user.email}</div>;
  },
  // Optional custom comparer — skip re-render if only `updatedAt` changed
  (prev, next) => prev.user.id === next.user.id && prev.user.email === next.user.email
);

function App() {
  const [tick, setTick] = useState(0);
  const user = { id: 1, name: 'Alice', email: 'alice@example.com' };

  return (
    <div>
      <UserCard user={user} />
      <button onClick={() => setTick(t => t + 1)}>Re-render Parent ({tick})</button>
      {/* UserCard does NOT re-render when tick changes */}
    </div>
  );
}

render(<App />, document.getElementById('app'));
```

--------------------------------

### Force synchronous state updates with flushSync

Source: https://context7.com/tanstack/preact/llms.txt

Employ flushSync to ensure Preact applies state updates synchronously before the function returns. This is crucial when DOM measurements or manipulations are needed immediately after a state change.

```jsx
import { render } from 'preact';
import { useState, useRef } from 'preact/hooks';
import { flushSync } from 'preact/compat';

function LiveList() {
  const [items, setItems] = useState(['Apple', 'Banana']);
  const listRef = useRef(null);

  const addItem = () => {
    flushSync(() => {
      setItems(prev => [...prev, `Item ${prev.length + 1}`]);
    });
    // DOM is updated synchronously here — safe to read layout
    const list = listRef.current;
    list.scrollTop = list.scrollHeight; // Scroll to bottom immediately
  };

  return (
    <div>
      <ul ref={listRef} style={{ height: '100px', overflowY: 'scroll' }}>
        {items.map((item, i) => <li key={i}>{item}</li>)}
      </ul>
      <button onClick={addItem}>Add Item</button>
    </div>
  );
}

render(<LiveList />, document.getElementById('app'));
```

--------------------------------

### useDebugValue

Source: https://context7.com/tanstack/preact/llms.txt

Displays a custom label in the Preact DevTools panel for custom hooks, making them easier to inspect. It accepts a value and an optional formatter function.

```APIDOC
## `useDebugValue(value, formatter?)` — Custom DevTools label for custom hooks

Displays a custom label in the Preact DevTools panel for custom hooks, making them easier to inspect.

```jsx
import { useDebugValue, useState, useEffect } from 'preact/hooks';

function useOnlineStatus() {
  const [online, setOnline] = useState(navigator.onLine);

  useDebugValue(online, status => `Network: ${status ? 'Online' : 'Offline'}`);

  useEffect(() => {
    const on = () => setOnline(true);
    const off = () => setOnline(false);
    window.addEventListener('online', on);
    window.addEventListener('offline', off);
    return () => {
      window.removeEventListener('online', on);
      window.removeEventListener('offline', off);
    };
  }, []);

  return online;
}

// DevTools will show: "Network: Online" next to the hook
```
```

--------------------------------

### useLayoutEffect for Synchronous DOM Effects

Source: https://context7.com/tanstack/preact/llms.txt

useLayoutEffect fires synchronously after DOM mutations but before paint, ideal for reading layout or synchronous re-renders to prevent flicker.

```jsx
import { render } from 'preact';
import { useRef, useLayoutEffect, useState } from 'preact/hooks';

function Tooltip({ text, children }) {
  const ref = useRef(null);
  const [style, setStyle] = useState({});

  useLayoutEffect(() => {
    // Read layout — this runs synchronously before paint to avoid flicker
    const rect = ref.current.getBoundingClientRect();
    setStyle({
      position: 'fixed',
      top: rect.bottom + 8 + 'px',
      left: rect.left + 'px'
    });
  }, [text]);

  return (
    <span ref={ref}>
      {children}
      <div class="tooltip" style={style}>{text}</div>
    </span>
  );
}

render(<Tooltip text="Helpful hint">Hover me</Tooltip>, document.getElementById('app'));
```

--------------------------------

### act(callback)

Source: https://context7.com/tanstack/preact/llms.txt

Wrap test interactions for reliable state flushing. Ensures all state updates and effects triggered by callback are processed before assertions. Works with both synchronous and asynchronous callbacks.

```APIDOC
## act(callback)

### Description
Wrap test interactions for reliable state flushing. Ensures all state updates and effects triggered by `callback` are processed before assertions. Works with both synchronous and asynchronous callbacks.

### Usage
```jsx
import { render } from 'preact';
import { act } from 'preact/test-utils';
import { useState } from 'preact/hooks';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <span id="count">{count}</span>
      <button id="btn" onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
}

// In a test (e.g., with vitest / jest + @testing-library/preact)
const container = document.createElement('div');
document.body.appendChild(container);

act(() => {
  render(<Counter />, container);
});

const btn = container.querySelector('#btn');

act(() => {
  btn.click();
  btn.click();
});

console.log(container.querySelector('#count').textContent); // "2"

// Async example
await act(async () => {
  btn.click();
  await new Promise(r => setTimeout(r, 0)); // Wait for async effects
});
```
```

--------------------------------

### Create a Mutable Ref with createRef

Source: https://context7.com/tanstack/preact/llms.txt

Create a mutable ref object that persists for the component's lifetime. Attach it to DOM elements or components using the ref prop to access their properties or methods.

```jsx
import { createRef, Component, render } from 'preact';

class TextInput extends Component {
  inputRef = createRef();

  focusInput = () => {
    this.inputRef.current.focus();
    console.log('Input value:', this.inputRef.current.value);
  };

  render() {
    return (
      <div>
        <input ref={this.inputRef} type="text" placeholder="Type here..." />
        <button onClick={this.focusInput}>Focus</button>
      </div>
    );
  }
}

render(<TextInput />, document.getElementById('app'));
```

--------------------------------

### Using `act` for Reliable State Flushing in Tests

Source: https://context7.com/tanstack/preact/llms.txt

Wrap test interactions with `act` to ensure all state updates and effects are processed before assertions. Works with synchronous and asynchronous callbacks.

```jsx
import { render } from 'preact';
import { act } from 'preact/test-utils';
import { useState } from 'preact/hooks';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <span id="count">{count}</span>
      <button id="btn" onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
}

// In a test (e.g., with vitest / jest + @testing-library/preact)
const container = document.createElement('div');
document.body.appendChild(container);

act(() => {
  render(<Counter />, container);
});

const btn = container.querySelector('#btn');

act(() => {
  btn.click();
  btn.click();
});

console.log(container.querySelector('#count').textContent); // "2"

// Async example
await act(async () => {
  btn.click();
  await new Promise(r => setTimeout(r, 0)); // Wait for async effects
});
```

--------------------------------

### Expose Imperative API with useImperativeHandle

Source: https://context7.com/tanstack/preact/llms.txt

Customize the imperative API exposed by a component when a parent accesses its ref. This hook must be used in conjunction with `forwardRef` from `preact/compat`.

```jsx
import { render } from 'preact';
import { useRef, useImperativeHandle } from 'preact/hooks';
import { forwardRef } from 'preact/compat';

const FancyInput = forwardRef((props, ref) => {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current.focus(),
    clear: () => { inputRef.current.value = ''; },
    getValue: () => inputRef.current.value
  }), []);

  return <input ref={inputRef} {...props} />; 
});

function Form() {
  const inputRef = useRef(null);

  return (
    <form onSubmit={e => {
      e.preventDefault();
      console.log('Value:', inputRef.current.getValue());
      inputRef.current.clear();
    }}>
      <FancyInput ref={inputRef} placeholder="Type something" />
      <button type="button" onClick={() => inputRef.current.focus()}>Focus</button>
      <button type="submit">Submit & Clear</button>
    </form>
  );
}

render(<Form />, document.getElementById('app'));
```

--------------------------------

### cloneElement

Source: https://context7.com/tanstack/preact/llms.txt

Clones and optionally modifies a VNode, creating a copy of a VNode and merging new props or replacing children.

```APIDOC
## cloneElement(vnode, props, ...children) — Clone and optionally modify a VNode

Creates a copy of a VNode, merging new props and optionally replacing children.

```jsx
import { cloneElement, render } from 'preact';

function Button({ children, ...props }) {
  return <button {...props}>{children}</button>;
}

function PrimaryButton({ children, ...props }) {
  const base = <Button>{children}</Button>;
  // Clone and inject extra props
  return cloneElement(base, { class: 'btn-primary', ...props });
}

render(<PrimaryButton onClick={() => alert('Clicked!')}>Save</PrimaryButton>, document.getElementById('app'));
// Renders: <button class="btn-primary">Save</button>
```
```

--------------------------------

### Global Lifecycle Hooks with options

Source: https://context7.com/tanstack/preact/llms.txt

Access and modify the global options object to hook into Preact's rendering pipeline. This is primarily used by libraries for features like devtools or hooks compatibility.

```js
import { options } from 'preact';

// Called every time a VNode is created
const prevVnode = options.vnode;
options.vnode = vnode => {
  if (prevVnode) prevVnode(vnode);
  console.log('VNode created:', vnode.type);
};

// Custom async rendering scheduler (e.g., replace with requestIdleCallback)
options.debounceRendering = cb => {
  requestIdleCallback(cb, { timeout: 100 });
};

// Intercept events before they reach handlers
options.event = e => {
  console.log('Event intercepted:', e.type);
  return e;
};
```

--------------------------------

### Forward Refs with forwardRef in Preact Compat

Source: https://context7.com/tanstack/preact/llms.txt

Allows a parent component to attach a ref directly to a DOM element inside a child component. The render function receives props and the ref, enabling imperative access to child DOM nodes.

```jsx
import { render } from 'preact';
import { useRef } from 'preact/hooks';
import { forwardRef } from 'preact/compat';

const TextArea = forwardRef(function TextArea({ label, ...props }, ref) {
  return (
    <label>
      {label}
      <textarea ref={ref} {...props} />
    </label>
  );
});
TextArea.displayName = 'TextArea';

function Form() {
  const textAreaRef = useRef(null);

  return (
    <div>
      <TextArea ref={textAreaRef} label="Notes:" rows={4} />
      <button onClick={() => {
        textAreaRef.current.focus();
        console.log('Content:', textAreaRef.current.value);
      }}>
        Focus & Read
      </button>
    </div>
  );
}

render(<Form />, document.getElementById('app'));
```