# Create a new Nexus entity

Add an entity to an existing module.

## Arguments

$ARGUMENTS — Entity type and name (e.g. "collection products", "single settings", "tree categories"). If only name given, defaults to collection.

## Step 1: Detect context

Find which module to add the entity to:

1. Check current directory — if inside `src/modules/{name}/`, use that module
2. Otherwise, list available modules and ask:
   ```bash
   ls src/modules/
   ```

## Step 2: Ask for details

Parse type from arguments (collection/single/tree/dag/view/computed). Then ask:

**For collection:**
- Table name (default: argument name)
- Label (en/es)
- Fields to include (suggest common ones)
- Timestamps? (default: yes)
- Soft delete? (default: no)
- CASL subject name

**For single:**
- Key name (e.g. "{module}_settings")
- Label
- Fields
- Default values

**For tree:**
- Table name
- Label
- Fields (id and a labelField at minimum)

## Step 3: Generate entity file

Create `src/modules/{module}/entities/{name}.ts`:

### Collection template

```typescript
import type { CollectionEntityDefinition } from '@gzl10/nexus-sdk'
import { useIdField, useTextField } from '@gzl10/nexus-sdk/fields'

export const {name}Entity: CollectionEntityDefinition = {
  table: '{table_name}',
  type: 'collection',
  label: { en: '{Label}', es: '{Etiqueta}' },
  labelField: '{first_text_field}',
  timestamps: true,

  fields: {
    id: useIdField(),
    // ... generated fields
  },

  casl: {
    subject: '{Subject}',
    permissions: {
      ADMIN: { actions: ['manage'] },
      EDITOR: { actions: ['read', 'create', 'update'] },
      USER: { actions: ['read'] }
    }
  }
}
```

### Single template

```typescript
import type { SingleEntityDefinition } from '@gzl10/nexus-sdk'

export const {name}Entity: SingleEntityDefinition = {
  type: 'single',
  key: '{key_name}',
  label: { en: '{Label}', es: '{Etiqueta}' },
  icon: 'Settings',

  fields: {
    // ... generated fields
  },

  defaults: {
    // ... matching fields
  }
}
```

### Tree template

```typescript
import type { TreeEntityDefinition } from '@gzl10/nexus-sdk'
import { useIdField, useTextField } from '@gzl10/nexus-sdk/fields'

export const {name}Entity: TreeEntityDefinition = {
  table: '{table_name}',
  type: 'tree',
  label: { en: '{Label}', es: '{Etiqueta}' },
  labelField: '{first_text_field}',

  fields: {
    id: useIdField(),
    // ... generated fields
  },

  seed: []
  // parent_id is auto-injected — do NOT define it
}
```

## Step 4: Update module manifest

Read the module's `index.ts`, add the import, and include in `definitions[]`:

```typescript
import { {name}Entity } from './entities/{name}.js'

// Add to definitions array
definitions: [...existing, {name}Entity]
```

## Step 5: Run migration

```bash
pnpm nexus migrate dev
```

## Gotchas

- Always use field factories from `@gzl10/nexus-sdk/fields`
- `required` is top-level, not inside `validation`
- Select options: direct array `[{value, label}]`
- Tree requires `seed` (can be `[]`)
- Single uses `key`, not `table`
- Entity updates use PUT (not PATCH) — relevant for hooks