# Create a new Nexus plugin

Scaffold a complete plugin project from scratch.

## Arguments

$ARGUMENTS — Plugin name (e.g. "bookmarks", "analytics", "notifications"). Lowercase, no spaces.

## Step 1: Ask for details

1. **Code** — exactly 3 lowercase chars, unique (e.g. "bkm", "anl", "ntf"). Validated: `/^[a-z]{3}$/`
2. **Category** — one of: content, data, assets, messaging, jobs, ai, analytics, integrations, commerce, security, legal, settings
3. **Description** — short description (en/es)
4. **Where to create** — default: current directory as `nexus-plugin-{name}/`

## Step 2: Generate scaffold

Create the following structure:

```
nexus-plugin-{name}/
├── src/
│   ├── index.ts              # PluginManifest + ModuleManifest
│   └── entities/
│       └── {name}.ts         # Example collection entity
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md
```

### package.json

```json
{
  "name": "@{scope}/nexus-plugin-{name}",
  "version": "1.0.0",
  "type": "module",
  "description": "{description}",
  "license": "MIT",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist", "migrations"],
  "scripts": {
    "build": "tsup",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests"
  },
  "peerDependencies": {
    "@gzl10/nexus-sdk": ">=0.14.0"
  },
  "devDependencies": {
    "@gzl10/nexus-sdk": "^0.14.0",
    "tsup": "^8.3.0",
    "typescript": "^5.7.0",
    "vitest": "^4.0.18"
  }
}
```

Ask the user for `@{scope}` (their npm scope).

### tsup.config.ts

```typescript
import { defineConfig } from 'tsup'
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'],
  dts: true,
  clean: true
})
```

### tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "declarationDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### src/index.ts

```typescript
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import type { PluginManifest, ModuleManifest } from '@gzl10/nexus-sdk'
import { {name}Entity } from './entities/{name}.js'

const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf-8')) as { name: string; version: string }

const {name}Module: ModuleManifest = {
  name: '{name}',
  label: { en: '{Name}', es: '{Nombre}' },
  icon: 'mdi:{icon}',
  category: '{category}',
  definitions: [{name}Entity]
}

export { {name}Module, {name}Entity }

export const {name}Plugin: PluginManifest = {
  name: pkg.name,
  code: '{code}',
  label: { en: '{Name}', es: '{Nombre}' },
  icon: 'mdi:{icon}',
  version: pkg.version,
  description: { en: '{description_en}', es: '{description_es}' },
  category: '{category}',
  modules: [{name}Module]
}

export default {name}Plugin
```

### Example entity

Generate a collection entity using the same pattern as `/nexus-new-entity` with basic fields (id, name, description).

### README.md

Generate with: what the plugin does, installation (`nexus plugin add`), configuration (if envVars), and entity descriptions.

## Step 3: Initialize

```bash
cd nexus-plugin-{name}
pnpm install
pnpm typecheck
```

## Gotchas

- `code` must be exactly 3 lowercase chars — validated by `registerPlugin()`
- `export default` the PluginManifest (plugins use default export, modules use named)
- **NEVER hardcode `name` or `version`** — read from `package.json` with `readFileSync`
- `peerDependencies` on `@gzl10/nexus-sdk` — not direct dependency
- `files: ["dist", "migrations"]` — include migrations dir even if empty initially
- Icons use Iconify format: `mdi:bookmark`, `mdi:chart-bar`, etc.
- Users install with `nexus plugin add`, not `pnpm add`