# Velt Activity Best Practices

> Velt Activity Logs implementation patterns and best practices for React, Next.js, and web applications. Use when adding real-time activity feeds, custom activity logging, audit trails, CRDT debounce configuration, server-side activity management via REST API, customizing the Activity Log wireframe with template variables (velt-data, velt-if, velt-class), or composing the VeltActivityLogWireframe sub-component tree (Header, Filter, List, DateGroup, Item, ShowMore, Empty, Loading).

- Skill: `velt-js/velt-activity-best-practices` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add velt-js/velt-activity-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/velt-js/velt-activity-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: velt-js (https://skillmd.com/u/velt-js)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/velt-js/velt-activity-best-practices

---


# 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