velt-activity-best-practices

Files (20)

• AGENTS.full.md
• AGENTS.md
• README.md
• SKILL.md
• metadata.json
• data-create-custom-hook.md · rules/react/data/
• data-subscribe-hook.md · rules/react/data/
• _sections.md · rules/shared/
• _template.md · rules/shared/
• config-action-type-filters.md · rules/shared/config/
• config-debounce.md · rules/shared/config/
• config-immutability.md · rules/shared/config/
• core-activity-log-component.md · rules/shared/core/
• core-setup.md · rules/shared/core/
• data-create-custom-api.md · rules/shared/data/
• data-subscribe-api.md · rules/shared/data/
• debug-common-issues.md · rules/shared/debug/
• rest-api.md · rules/shared/rest/
• ui-wireframes.md · rules/shared/ui/
• wireframe-variables-activity-log.md · rules/shared/wireframe-variables/

SKILL.md (first lines)

# Velt Activity Logs Best Practices

Comprehensive implementation guide for Velt's activity log system in React and Next.js applications. Contains 13 rules across 7 categories, prioritized by impact to guide automated code generation and integration patterns.

## When to Apply

Reference these guidelines when:
- Adding real-time activity feeds to a React/Next.js application
- Subscribing to collaboration events via useAllActivities or getAllActivities
- Creating custom activity records for non-Velt events
- Configuring CRDT activity debounce to reduce feed noise
- Enabling immutability for compliance audit trails
- Filtering activities by feature type or action type
- Managing activity records server-side via REST API
- Customizing the Activity Log wireframe with template variables (`velt-data`, `velt-if`, `velt-class`)
- Composing the `VeltActivityLogWireframe` sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading)
- Debugging activity log issues (records not appearing, null loading states)

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Core Setup | CRITICAL | `core-` |
| 2 | Data Access | HIGH | `data-` |
| 3 | Configuration | MEDIUM | `config-` |
| 4 | Wireframe Variables | MEDIUM | `wireframe-variables-` |
| 5 | UI Wireframes | MEDIUM | `ui-` |
| 6 | REST API | LOW-MEDIUM | `rest-` |
| 7 | Debugging & Testing | LOW-MEDIUM | `debug-` |

## Quick Reference

### 1. Core Setup (CRITICAL)

- `core-setup` — Enable Activity Logs in Velt Console
- `core-activity-log-component` — Use VeltActivityLog component to display activity feed UI

### 2. Data Access (HIGH)

- `data-subscribe-hook` — Use useAllActivities hook for real-time activity feeds (React)
- `data-subscribe-api` — Use getAllActivities API for real-time activity subscriptions
- `data-create-custom-hook` — Use useActivityUtils to create custom activities (React)
- `data-create-custom-api` — Use getActivityElement API to create custom activities

### 3. Configuration (MEDIUM)

- `config-debounce` — Configure CRDT activity debounce time
- `config-immutability` — Enable immutability for audit trails
- `config-action-type-filters` — Use action type constants for type-safe filtering

### 4. Wireframe Variables (MEDIUM)

- `wireframe-variables-activity-log` — Bind Activity Log wireframe slots using `velt-data`, `velt-if`, `velt-class`, the cross-cutting `defaultCondition` prop, and Angular signal inputs (`[componentConfigSignal]`, `[parentLocalUIState]`)

### 5. UI Wireframes (MEDIUM)

- `ui-wireframes` — Compose the `VeltActivityLogWireframe` sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading) inside `VeltWireframe`

### 6. REST API (LOW-MEDIUM)

- `rest-api` — Use REST APIs for server-side activity management

### 7. Debugging & Testing (LOW-MEDIUM)

- `debug-common-issues` — Debug common activity log issues

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/shared/core/core-setup.md
rules/react/data/data-subscribe-hook.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Source pointers to official documentation

## Compiled Documents

- `AGENTS.md` — Compressed index of all rules with file paths (start here)
- `AGENTS.full.md` — Full verbose guide with all rules expanded inline

From velt-js/velt-plugin-cursor, MIT.