# Layers

> I use Nuxt Layers to structure my application. This allows me to create a modular architecture that is easy to maintain and extend.

Nuxt Layers is a powerful feature that allows you to create modular applications by composing different layers. Each layer can contain its own configuration, components, and modules, making it easy to share and reuse code across different projects.

## What layers are included in this starter kit?

This starter kit contains layers in the `/packages` directory:

### Core Layers

- **layer-core**: Base layer containing shared composables, components & server routes:
  - `useAppToast`: Toast notifications with success, error, info, warn methods
  - `useConfirmationModal`: Confirmation modals
  - `useLoadingModal`: Loading modals
  - `useLogger`: Client-side logging (wraps consola)
  - Server utilities for logging and masking sensitive data
- **layer-emails**: Email templates and sending functionality:
  - Nuxt Email Renderer components for templates
  - `useEmail()` composable with pre-built email methods
  - Templates in `app/emails/` directory

### Feature Layers

- **layer-auth**: Authentication using better-auth:
  - Email/password authentication
  - Social login (Google, GitHub)
  - Database schema in `server/db/schema/auth.ts`
  - `useAuth()` composable for client
  - `requireAuth()`, `useServerAuth()` for server
- **layer-payment**: Payment integration with Polar.sh:
  - Uses `@polar-sh/better-auth` plugin
  - `useBilling()` composable
  - Server utilities for Polar customer management
- **layer-storage**: File storage handling
  - File upload and management
  - Database schema in `server/db/schema/file.ts`
- **layer-dashboard**: User dashboard:
  - Extends layer-auth, layer-payment, layer-storage, layer-testimonials
  - User settings, billing management
  - Admin panel features
- **layer-testimonials**: Testimonials management:
  - Public testimonials display
  - Admin management interface
  - Database schema in `server/db/schema/testimonial.ts`
- **layer-waitlist**: Waitlist functionality:
  - User signups
  - Email verification
  - Database schema in `server/db/schema/waitlist.ts`
- **layer-blog**: Blog functionality:
  - Blog posts with Nuxt Content
  - RSS feed generation
- **layer-docs**: Documentation pages:
  - Documentation with Nuxt Content
  - Search functionality

## Layer Dependency Graph

```text
apps/web extends:
  ├─ layer-dashboard (requires layer-auth, layer-payment, layer-storage, layer-testimonials)
  ├─ layer-testimonials (requires layer-auth)
  ├─ layer-blog (requires layer-core)
  ├─ layer-waitlist (requires layer-auth)
  └─ layer-docs (requires layer-auth)

layer-dashboard extends:
  ├─ layer-auth
  ├─ layer-payment (requires layer-auth)
  ├─ layer-storage (requires layer-auth)
  └─ layer-testimonials (requires layer-auth)

layer-auth extends:
  ├─ layer-core (base layer)
  └─ layer-emails (requires layer-core)
```

## Referencing Layers

**Important**: Layers are referenced by **name only**, not by path. They're workspace packages managed by pnpm.

✅ Correct:

```typescript
export default defineNuxtConfig({
  extends: ['layer-auth', 'layer-core']
})
```

❌ Wrong:

```typescript
export default defineNuxtConfig({
  extends: ['../packages/layer-auth']
})
```

## Remove a layer

To remove a layer:

1. Delete the corresponding directory in `/packages`
2. Remove it from `extends` in your `nuxt.config.ts`
3. Search for references to the layer throughout the codebase
4. Remove its dependencies from `package.json` if no longer needed
5. Update any imports that reference the layer

## Adding a new layer

1. Create a new directory in `/packages/layer-<name>`
2. Add `package.json` with the layer name
3. Create `nuxt.config.ts` to configure the layer
4. Add the layer to `extends` in `apps/web/nuxt.config.ts`
5. Reference it by name in your extends array