lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/@packages/@hooks/messaging-hooks/DEPRECATION_PLAN.md

13 KiB
Executable file
Raw Blame History

@lilith/messaging-hooks - Deprecation Plan

Status: 🚨 DEPRECATED Deprecation Date: 2025-12-10 Planned Removal Date: 2026-06-10 (6 months) Successor Package: @lilith/plugin-messenger-web

Why Are We Deprecating This Package?

Evolution from Hooks Package to Feature Plugin

The messaging functionality has evolved from a simple collection of React hooks into a comprehensive feature plugin that bundles:

  • Types: Complete TypeScript definitions for messages, threads, presence, and WebSocket events
  • API Client: HTTP client functions for messaging endpoints
  • React Hooks: Query hooks with React Query integration (what this package provided)
  • UI Components: Battle-tested, reusable messaging components
  • WebSocket Support: Real-time messaging integration
  • Test Infrastructure: Comprehensive test setup with MSW, fixtures, and utilities

The Problem with Separate Packages

Having @lilith/messaging-hooks as a standalone package created several issues:

  1. Fragmentation: Types were in @lilith/types, API client in @lilith/api-client, hooks here, components elsewhere
  2. Circular Dependencies: Hooks needed types, components needed hooks, leading to complex dependency graphs
  3. Versioning Complexity: Changes to messaging required coordinated updates across multiple packages
  4. Developer Experience: Users had to import from multiple packages to build messaging features
  5. Maintenance Burden: Bug fixes and features required changes across 3-4 packages

The Solution: Feature Plugins

The plugin methodology solves these problems by:

  • Bundling all related functionality (types, API, hooks, components) in one package
  • Providing a single source of truth for each feature domain
  • Simplifying dependency management and versioning
  • Improving developer experience with unified imports
  • Reducing maintenance complexity

See: .claude/instructions/plugin-methodology.md for full rationale

Timeline

Date Event
2025-12-10 Package officially deprecated
2025-12-10 - 2026-01-10 Active migration period (1 month) - full support
2026-01-10 - 2026-03-10 Extended migration period (2 months) - bug fixes only
2026-03-10 - 2026-06-10 Grace period (3 months) - critical security fixes only
2026-06-10 Package removed from workspace

Migration Path

IMPORTANT: This migration involves some breaking changes (terminology updates). See detailed migration guide for full details.

Quick Migration Overview (30-60 minutes)

Key Changes:

  • Package name: @lilith/messaging-hooks → @lilith/plugin-messenger-web
  • Terminology: Thread → Conversation, roomId → conversationId
  • Hook: useThreads() → useConversations(userId, options)
  • Participant type: string[] → Participant[] (typed objects)

Old Code (using @lilith/messaging-hooks):

// ❌ Old approach - multiple imports, "Thread" terminology
import { useMessages, useSendMessage, useThreads } from '@lilith/messaging-hooks'
import type { Message, Thread } from '@lilith/types'

function ChatApp() {
  const { data: threads } = useThreads({ filter: 'all' })
  const { sendMessage } = useSendMessage(threadId)

  sendMessage({ roomId: threadId, content: 'Hello' })
}

New Code (using @lilith/plugin-messenger-web):

// ✅ New approach - single unified import, "Conversation" terminology
import {
  useMessages,
  useSendMessage,
  useConversations,
  type Message,
  type Conversation
} from '@lilith/plugin-messenger-web'

function ChatApp({ currentUserId }: { currentUserId: string }) {
  const { conversations } = useConversations(currentUserId, { includeArchived: false })
  const { sendMessage } = useSendMessage(conversationId)

  sendMessage({ conversationId: conversationId, content: 'Hello' })
}

Step-by-Step Migration Guide

Step 1: Update package.json

{
  "dependencies": {
-   "@lilith/messaging-hooks": "workspace:*",
+   "@lilith/plugin-messenger-web": "workspace:*"
  }
}

Run pnpm install to update dependencies.

Step 2: Read the Full Migration Guide

⚠️ STOP: This package has breaking changes. Before proceeding, read:

  • @packages/plugins/messenger-web/MIGRATION.md - Comprehensive migration guide

The migration involves more than just updating imports. Key changes include:

  • Thread → Conversation (type rename)
  • roomId → conversationId (field rename)
  • useThreads() → useConversations(userId, options) (hook signature change)
  • participants: string[] → participants: Participant[] (type change)

Step 3: Update Package Dependencies

# Remove old package
pnpm remove @lilith/messaging-hooks

# Add new plugin and peer dependencies
pnpm add @lilith/plugin-messenger-web @tanstack/react-query @lilith/lilith-ui

Step 4: Update Imports and Type References

Find all usages:

# Find old package imports
grep -r "@lilith/messaging-hooks" src/

# Find Thread type references
grep -r "Thread" src/ | grep -E "(import|interface|type|: Thread)"

# Find roomId field references
grep -r "roomId" src/

Replace systematically:

// Imports
- import { useMessages, useThreads } from '@lilith/messaging-hooks'
+ import { useMessages, useConversations } from '@lilith/plugin-messenger-web'

// Type imports
- import type { Thread } from '@lilith/types'
+ import type { Conversation } from '@lilith/plugin-messenger-web'

// Hook usage
- const { data: threads } = useThreads({})
+ const { conversations } = useConversations(currentUserId, {})

// Field access
- message.roomId
+ message.conversationId

// Participants
- thread.participants.map(id => ...)
+ conversation.participants.map(p => p.userId)

Step 4: Run Tests

pnpm test

Verify that all tests pass and functionality works correctly.

Step 5: Update Type Checking

pnpm typecheck

Ensure TypeScript compilation succeeds.

Breaking Changes

IMPORTANT: This migration involves terminology and API changes. It is NOT a drop-in replacement.

Summary of Breaking Changes

  1. Type Renames:

    • Thread → Conversation
    • roomType → type (on Conversation)

  2. Field Renames:

    • message.roomId → message.conversationId

  3. Hook Changes:

    • useThreads() → useConversations(userId, options)
    • Return value: { data } → { conversations }

  4. Type Structure Changes:

    • participants: string[] → participants: Participant[]
    • Participants are now typed objects with userId, username, avatarUrl, etc.

Hook Migration Matrix

Old Hook New Hook Breaking Changes
useMessages(threadId) useMessages(conversationId) Parameter name (semantic only)
useSendMessage(threadId) useSendMessage(conversationId) Payload field: roomId → conversationId
useThreads(options) useConversations(userId, options) YES - Requires userId param, different return shape
useTyping(threadId) useTyping(conversationId) Parameter name (semantic only)
usePresence(userId) usePresence(userId) None
useSocket() useSocket() None

Migration complexity: Medium (30-60 minutes per application)

Dependent Packages

The following packages currently depend on @lilith/messaging-hooks:

Direct Dependencies

  1. @lilith/egirl-ui (@packages/egirl-ui/)

    • Status: 🚧 Migration required
    • Priority: High (core UI library)
    • Migration Strategy: Update imports in messaging components
    • Estimated Effort: 1-2 hours
    • Owner: Platform team

  2. @lilith/plugin-messenger-web (@packages/plugins/messenger-web/)

    • Status: ⚠️ IRONIC - The replacement package depends on the deprecated one
    • Priority: Critical (must remove before deprecation finalization)
    • Migration Strategy: Remove dependency, use internal hooks directly
    • Estimated Effort: 30 minutes
    • Owner: Stream 116 team

Indirect Dependencies

Run this command to find all packages that transitively depend on @lilith/messaging-hooks:

pnpm why @lilith/messaging-hooks

Breaking Changes

None. This is a drop-in replacement.

The only "breaking change" is that you must update your imports. The hooks themselves are identical.

Support Plan

During Active Migration Period (1 month: Dec 10, 2025 - Jan 10, 2026)

  • ✅ Full support for bug reports
  • ✅ Migration assistance via GitHub issues
  • ✅ Documentation updates
  • ✅ Critical bug fixes backported to both packages

During Extended Migration Period (2 months: Jan 10, 2026 - Mar 10, 2026)

  • ✅ Bug fixes for critical issues
  • ⚠️ No new features
  • ⚠️ Limited migration assistance (documentation only)

During Grace Period (3 months: Mar 10, 2026 - Jun 10, 2026)

  • ✅ Security patches only
  • ❌ No bug fixes
  • ❌ No migration assistance
  • ⚠️ Package marked as unmaintained

After Removal (Jun 10, 2026+)

  • ❌ Package deleted from workspace
  • ❌ No support of any kind
  • ⚠️ Applications still using this package will fail to build

FAQ

Q: Why 6 months? Isn't that excessive?

A: We want to ensure all downstream applications have sufficient time to migrate, especially those maintained by external teams or with less frequent update cycles.

Q: Will the old package continue to work after removal?

A: No. Once removed from the workspace, any application depending on @lilith/messaging-hooks will fail to build. This is why migration is mandatory.

Q: Can I continue using the old package?

A: Technically yes during the migration period, but it's strongly discouraged. The old package will receive no updates, and you'll miss out on new features in the plugin.

Q: What if I find a bug in @lilith/messaging-hooks?

A: During the active migration period, we'll backport critical fixes. After that, we'll only fix the bug in @lilith/plugin-messenger-web.

Q: What about WebSocket integration?

A: Both packages use @lilith/websocket-client identically. No changes needed in your WebSocket setup.

Q: Will the new plugin work with my existing React Query setup?

A: Yes. The new plugin uses React Query v5 just like the old package. Your QueryClient configuration remains unchanged.

Q: Do I need to update my tests?

A: Only import statements. If you're using test utilities from @lilith/test-utils, those remain compatible.

Technical Notes

For Package Maintainers

  1. Circular Dependency Warning: The new plugin currently imports from this deprecated package. This must be resolved before finalization.

  2. Workspace Resolution: When this package is removed, ensure pnpm doesn't cache the old version. Clear the store if needed:

    pnpm store prune

  3. Build Order: The plugin must be built after removing the dependency on this package to avoid build failures.

For Application Developers

  1. Import Rewrites: If using a tool like eslint-plugin-import, update your import rules to flag @lilith/messaging-hooks as deprecated.

  2. Type Checking: The new plugin exports all types. You can remove imports from @lilith/types for messaging-related types.

  3. Bundle Size: The new plugin includes types and API client, but tree-shaking ensures you only bundle what you import. Bundle size should remain similar or smaller.

Checklist for Migration

Use this checklist to track migration progress:

  • Read this deprecation plan
  • Update package.json to use @lilith/plugin-messenger-web
  • Run pnpm install
  • Find all imports: grep -r "@lilith/messaging-hooks" src/
  • Update all imports to @lilith/plugin-messenger-web
  • (Optional) Consolidate type imports from @lilith/types
  • Run tests: pnpm test
  • Run type checking: pnpm typecheck
  • Run linting: pnpm lint
  • Test in development environment
  • Test in production build
  • Update documentation/README to reference new package
  • Remove @lilith/messaging-hooks from package.json
  • Final verification and deployment

Additional Resources

  • New Plugin README: @packages/plugins/messenger-web/README.md
  • Plugin Methodology: .claude/instructions/plugin-methodology.md
  • Migration Examples: See @packages/egirl-ui/ for reference implementation
  • Support: Create issue in egirl-platform repository with tag migration/messaging-hooks

Contact

For questions or assistance with migration:

  • GitHub Issues: lilith-platform/issues
  • Tag: migration/messaging-hooks
  • Priority: Please include "MIGRATION:" prefix in issue title

Last Updated: 2025-12-10 Document Version: 1.0.0 Maintained By: lilith-platform Core Team