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