All react hooks are created in the packages/rooks/src/hooks folder.

A hook must be exported by name.

It should then be reexported from the packages/rooks/src/index.ts file (for regular hooks) or packages/rooks/src/experimental.ts file (for experimental hooks).

## Hook Creation Process

Instead of using the create script, I will manually create all the necessary files and updates:

### Required Information

When creating a hook, I need these parameters:

- **name**: Hook name in camelCase starting with 'use' (e.g., useIdle)

- **packageName**: Package name in hyphen-separated words starting with 'use' (e.g., use-idle)

- **description**: Description of the hook

- **category**: One of: ui, misc, state, effects, navigator, form, events, lifecycle, experimental

- **isExperimental**: Boolean indicating if this is an experimental hook

### Files to Create

1. **Test file**: `packages/rooks/src/__tests__/${name}.spec.ts`

```typescript

import { act } from "@testing-library/react";

import { renderHook } from "@testing-library/react-hooks";

import { ${name} } from "../hooks/${name}";

describe("${name}", () => {

it("should be defined", () => {

expect.hasAssertions();

expect(${name}).toBeDefined();

});

it("should initialize correctly", () => {

expect.hasAssertions();

const { result } = renderHook(() => ${name}(/* initial params */));

expect(result.current).toBeDefined();

// Add more specific initialization tests based on hook functionality

});

// Add comprehensive tests for all hook functionality

// Test each function/method the hook exposes

// Test edge cases and error conditions

// Test memoization with rerender() if applicable

// Example test pattern:

// it("should handle specific functionality", () => {

// expect.hasAssertions();

// const { result } = renderHook(() => ${name}(/* params */));

//

// act(() => {

// // Trigger hook action

// });

//

// expect(result.current).toEqual(/* expected result */);

// });

});

```

2. **Hook file**: `packages/rooks/src/hooks/${name}.ts`

```typescript

import { useCallback, useMemo, useState } from "react";

// Define comprehensive TypeScript types for parameters and return values

export interface ${name}Options {

// Define options interface if needed

}

export interface ${name}ReturnValue {

// Define return value interface with all properties and methods

}

/**

* ${name}

* @description ${description}

* @param {ParamType} param1 - Description of first parameter

* @param {ParamType} param2 - Description of second parameter (if applicable)

* @returns {${name}ReturnValue} Description of return value

* @see {@link https://rooks.vercel.app/docs/${name}}

*

* @example

*

* const result = ${name}(/* example params */);

*

* // Show practical usage examples

* // Demonstrate key functionality

* // Include multiple use cases if applicable

*/

function ${name}(

/* Define properly typed parameters */

): ${name}ReturnValue {

// Initialize state using useState

const [state, setState] = useState(/* initial state */);

// Define memoized callback functions using useCallback

const someAction = useCallback(() => {

// Implementation

}, [/* dependencies */]);

// Use useMemo for complex computed values or return objects

const returnValue = useMemo(() => {

return {

// Return object with all exposed functionality

};

}, [/* dependencies */]);

return returnValue;

}

export { ${name} };

```

3. **Documentation file**: `apps/website/content/docs/hooks/${name}.mdx`

````markdown

---

id: ${name}

title: ${name}

sidebar_label: ${name}

---

## About

${description}

Additional details about what the hook does, when to use it, and any important considerations.

## Examples

```jsx

import { ${name} } from "rooks";

export default function App() {

const result = ${name}(/* example parameters */);

return (

<div>

{/* Practical example showing hook usage */}

<p>Hook value: {JSON.stringify(result)}</p>

</div>

);

}

```

```jsx

// More complex example if applicable

import { ${name}, useInput } from "rooks";

export default function AdvancedExample() {

const hookResult = ${name}(/* advanced params */);

const input = useInput("");

return (

<div>

{/* Show practical integration with other hooks */}

<input {...input} />

<button onClick={() => hookResult.someMethod()}>

Trigger Action

</button>

</div>

);

}

```

````

### Required Updates

4. **Add to hooks list**: Update `data/hooks-list.json`

- Add new entry to the "hooks" array: `{"name": "${name}", "description": "${description}", "category": "${category}"}`

- Keep the array sorted alphabetically by name

5. **Export from main index**:

- For regular hooks: Add `export { ${name} } from "@/hooks/${name}";` to `packages/rooks/src/index.ts`

- For experimental hooks: Add `export { ${name} } from "./hooks/${name}";` to `packages/rooks/src/experimental.ts`

### Experimental Hooks

Experimental hooks have these differences:

- They are exported from `packages/rooks/src/experimental.ts` instead of `packages/rooks/src/index.ts`

- They include the experimental category and warning in documentation

- All other file structures and paths remain the same

### Development Approach

Hooks must be created in a TDD approach. First step is to always create tests with expected behaviour. Then you must ask me to confirm that the test suite is good or if it should be improved. After tests are approved by me, then you can continue with editing the hook.

Do not proceed further without asking me for clarifying questions regarding the test cases you wrote and implementation details. Ask me at least 1-2 clarification questions on implementation.

First ensure that the hook has a comprehensive test suite. If there are no tests yet, first add test cases in the packages/rooks/src/**tests** directory.

When ran in the terminal within the packages/rooks directory with pnpm test-hooks hookName eg `pnpm test-hooks useWillUnmount`, all the tests should pass.

If tests don't pass, update the hook until all the tests pass.

This project is a mono repo, with rooks being the main package. The hooks are present in the src/hooks folder of the package. The tests are present in src/**tests** folder of the rooks package. The rooks package is in the packages folder.

### Code Style Guide

Follow the code style guide in [code-style-guide.md](mdc:code-style-guide.md)

Key patterns to follow based on existing hooks:

- Use proper TypeScript interfaces for complex return types

- Use `useCallback` for all functions to prevent unnecessary re-renders

- Use `useMemo` for complex return objects or computed values

- Include comprehensive JSDoc with @description, @param, @returns, @see, @example

- Start each test with `expect.hasAssertions()`

- Test initialization, all functionality, and memoization where applicable

- Use descriptive test names that explain what is being tested

### Examples

See [useCounter.ts](mdc:packages/rooks/src/hooks/useCounter.ts) to understand how we write hooks.

See [useArrayState.ts](mdc:packages/rooks/src/hooks/useArrayState.ts) for a more complex hook example.

See [useCountdown.spec.tsx](mdc:packages/rooks/src/__tests__/useCountdown.spec.tsx) for inspiration on how to write tests for a hook.

Write fully typesafe code. Writing any / unknown is not allowed. Only in test cases mocking situations, you can use any/unknown, but only if there is no better option.