Strapi 5 Cursor mdc rules

strapi5.mdc

---
description: 
globs: 
alwaysApply: true
---
## Types

- All types are located in the `/types` folder at the root.
- Before creating new types, always check existing ones.

---
## Code Style and Structure

**General Guidelines:**
- Always use **TypeScript**.
- Write **clear, modular TypeScript code** with proper type definitions. Types should be located in the `/types` folder.
- Follow **functional programming patterns**; avoid classes.
- Use **descriptive variable names** (e.g., `isLoading`, `hasPermission`).
- Implement proper **error handling and logging**.
- Do not modify the `tsconfig.json` file.

**Strapi 5 Specifics:**
- Always refer to the official **Strapi 5 documentation**.
- **Do not use `entityService`**. Instead, use the new **Document Service**.
- Use the new **Document** feature, which represents all variations of content for a given content-type entry.

**Document Service Update Example:**
```typescript
channel = await strapi.documents('api::channel.channel').update({
    documentId: existingChannel.documentId,
    data: {
        value: phoneNumber,
        validation_code: validationCode,
        is_validated: false,
        validation_status: 'pending'
    }
});
````

-----

## Official Documentation

  - **Refer to the official Strapi version 5 documentation** for all development.
  - Stay updated with V5 changes and guidelines.
  - Continuously monitor Strapi V5 updates.

-----

## Plugin Extensions

  - When extending controllers, services, or routes from plugins, use the `strapi-server.ts` file.

**Example: User-Permissions Registration Configuration**

```typescript
export default ({ env }) => ({
  // ...
  "users-permissions": {
    config: {
      register: {
        allowedFields: ["nickname"],
      },
    },
  },
  // ...
});
```

-----

## Custom Routes

  - For custom routes, create a separate file (e.g., `01-custom-route.ts`, `custom-channels-route.ts`). The naming convention should ensure clarity and organization.

**Example:**

```typescript
export default {
  routes: [
    {
      method: 'POST',
      path: '/channels/send-code',
      handler: 'channel.sendCode',
      policies: ['global::is-authenticated'],
    },
    {
      method: 'POST',
      path: '/channels/validate-code',
      handler: 'channel.validateCode',
      policies: ['global::is-authenticated'],
    }
  ]
}
```

-----

## Database Queries

  - Always follow the Strapi 5 Documentation and decide whether to use the Document Service or direct Database Queries based on the specific use case.
  - For single database operations, refer to the official documentation: [https://docs.strapi.io/dev-docs/api/query-engine/single-operations](mdc:https:/docs.strapi.io/dev-docs/api/query-engine/single-operations)

**Example: `findOne` Database Query**

```typescript
const entry = await strapi.db.query('api::blog.article').findOne({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  populate: { category: true },
});
```

**Example: `findMany` Database Query**

```typescript
const entries = await strapi.db.query('api::blog.article').findMany({
  select: ['title', 'description'],
  where: { title: 'Hello World' },
  orderBy: { publishedAt: 'DESC' },
  populate: { category: true },
});
```