> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleap.co/llms.txt
> Use this file to discover all available pages before exploring further.

# NPM Packages

> Install and use third-party packages

Extend your app's functionality with NPM packages.

## Installing Packages

### Via AI

Simply ask:

```
"Install react-hook-form for better form handling"
```

```
"Add date-fns for date formatting"
```

The AI will:

1. Add the package to package.json
2. Import it where needed
3. Use it in your code

### Automatic Installation

When AI writes code using a package, it's automatically installed on next preview refresh.

## Popular Packages

### Forms

| Package                 | Use Case              |
| ----------------------- | --------------------- |
| **react-hook-form**     | Form state management |
| **zod**                 | Schema validation     |
| **@hookform/resolvers** | Zod + react-hook-form |

```
"Add a contact form using react-hook-form with Zod validation"
```

### Dates

| Package      | Use Case                     |
| ------------ | ---------------------------- |
| **date-fns** | Date formatting/manipulation |
| **dayjs**    | Lightweight date library     |

```
"Format the created_at date using date-fns"
```

### UI Enhancements

| Package             | Use Case             |
| ------------------- | -------------------- |
| **framer-motion**   | Animations           |
| **react-hot-toast** | Toast notifications  |
| **sonner**          | Modern toast library |

```
"Add entrance animations using framer-motion"
```

### Data Fetching

| Package                   | Use Case                |
| ------------------------- | ----------------------- |
| **@tanstack/react-query** | Data fetching & caching |
| **swr**                   | Data fetching hooks     |

```
"Use React Query to fetch and cache the user data"
```

### Charts

| Package             | Use Case           |
| ------------------- | ------------------ |
| **recharts**        | React charts       |
| **chart.js**        | Canvas charts      |
| **react-chartjs-2** | Chart.js for React |

```
"Add a line chart showing monthly revenue using recharts"
```

### Utilities

| Package    | Use Case            |
| ---------- | ------------------- |
| **lodash** | Utility functions   |
| **clsx**   | Conditional classes |
| **uuid**   | Generate unique IDs |

## Using Installed Packages

Once installed, use in your code:

```typescript theme={null}
// Importing
import { format } from 'date-fns';
import { motion } from 'framer-motion';
import { useForm } from 'react-hook-form';

// Using
const formattedDate = format(new Date(), 'MMM d, yyyy');
```

## Pre-Installed Packages

These are already available:

### Core

* `astro` - Framework (static site generator)
* `react` - UI library (React 19, for interactive islands)
* `typescript` - Type safety
* `tailwindcss` - Styling (Tailwind v4)

### UI & Icons

Your interactive React islands can pull from the React 19 ecosystem:

* `lucide-react` - Icons
* `motion` - Animations
* `radix-ui` - Headless, accessible component primitives
* `clsx` - Class utilities
* `tailwind-merge` - Tailwind class merging

### Database

* `@/lib/kleap-db` - **Kleap Database** client. Use this for reading and writing data — you don't need to install a separate database client.

## Package Versions

### Checking Versions

Ask AI to check or update:

```
"What version of react-hook-form is installed?"
```

```
"Update framer-motion to the latest version"
```

### Version Compatibility

The AI typically installs compatible versions. If you need a specific version:

```
"Install react-hook-form version 7.48.0"
```

## TypeScript Types

Many packages include types. For those that don't:

```
"Install the TypeScript types for lodash"
```

This adds `@types/lodash`.

## Common Package Tasks

### Add Authentication

Kleap Database includes built-in email/password accounts, so ask for that
directly instead of installing a separate auth library:

```
"Add email and password login using Kleap Database accounts"
```

### Add Email Notifications

For an email whenever someone submits a form, use built-in **Forms** — no package needed. Sending custom transactional email from a static site requires an external provider called from your own backend (advanced):

```
"Add a contact form that emails me on each submission"
```

### Add Markdown

```
"Add support for rendering markdown content using react-markdown"
```

### Add PDF Generation

```
"Install @react-pdf/renderer for generating PDF invoices"
```

## Package Size Considerations

Be mindful of bundle size:

### Check Size

Use [bundlephobia.com](https://bundlephobia.com) to check package sizes.

### Lightweight Alternatives

| Heavy     | Lighter Alternative           |
| --------- | ----------------------------- |
| moment.js | date-fns, dayjs               |
| lodash    | lodash-es, individual imports |
| axios     | native fetch                  |

### Tree Shaking

Import only what you need:

```typescript theme={null}
// ❌ Imports entire library
import _ from 'lodash';

// ✅ Imports only needed function
import debounce from 'lodash/debounce';
```

## Build-Time vs Browser Packages

### Build-Time Only

Some packages should only run at build time, in Astro frontmatter (the code
between the `---` fences in a `.astro` file). This code never ships to the browser:

```astro theme={null}
---
// Runs at build time only
import { someBuildThing } from 'build-package';
const data = await someBuildThing();
---
```

### Browser (Interactive Islands)

Packages that need browser APIs run inside a React island, hydrated with a
`client:*` directive:

```astro theme={null}
---
import Widget from '../components/Widget.jsx';
---
<Widget client:load />
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Package not found">
    * Check package name spelling
    * Package might not exist on npm
    * Try searching npmjs.com for correct name
  </Accordion>

  <Accordion title="Module not found after install">
    * Refresh the preview
    * Package might need time to install
    * Check import path is correct
  </Accordion>

  <Accordion title="Types not found">
    * Install @types/package-name
    * Some packages include types already
    * Check package documentation
  </Accordion>

  <Accordion title="Version conflict">
    * Ask AI to resolve version conflict
    * Check peer dependencies
    * May need to update other packages
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Use established packages" icon="star">
    Choose well-maintained packages with good documentation
  </Card>

  <Card title="Check bundle size" icon="weight">
    Consider impact on app performance
  </Card>

  <Card title="Import selectively" icon="filter">
    Import only functions you need
  </Card>

  <Card title="Keep updated" icon="arrows-rotate">
    Update packages for security fixes
  </Card>
</CardGroup>

<Card title="Custom Fonts" icon="font" href="/tips/custom-fonts">
  Add typography packages
</Card>