name: "migrate-to-shared" description: "Migrate code from quorum-desktop to quorum-shared. Activates when moving utils, hooks, or components to the shared package. Guides the full workflow: analysis, copy, refactor imports, update barrel, delete local source, verify builds on web and mobile."

Migrate to quorum-shared

Guide for migrating code from quorum-desktop to @quilibrium/quorum-shared so it can be consumed by all Quorum apps (web, mobile, Electron).

Trigger phrases: "migrate to shared", "move to shared", "extract to shared", "share this with mobile", "move this to quorum-shared"

Prerequisites

Before starting any migration:

1. Confirm link: dependency is active in d:/GitHub/Quilibrium/quorum-desktop/package.json:

   "@quilibrium/quorum-shared": "link:../quorum-shared"
   

   If not, set it and run yarn install.

2. Confirm both repos are on the correct branch — if using stacked PRs, the migration branch should be based on the latest shared branch. Check with the user which branch to use.

3. Confirm quorum-shared builds cleanly before making changes:

   cd d:/GitHub/Quilibrium/quorum-shared && yarn build
   

Phase 1: Analyze What to Migrate

Before copying anything, classify every file/function the user wants to migrate.

Decision Matrix

Dependency Analysis

For each candidate file, check:

# What does this file import?
grep "^import" d:/GitHub/Quilibrium/quorum-desktop/src/<path-to-file>

# What imports this file?
grep -r "from.*<module-name>" d:/GitHub/Quilibrium/quorum-desktop/src/ --include="*.ts" --include="*.tsx" -l

Classify imports into:

• Shared types (@quilibrium/quorum-shared) — already available, change to relative in shared
• npm packages — check if they exist in shared's package.json, add if missing
• Desktop-only modules — these block migration unless refactored
• @lingui/core/macro — strip and replace with plain English defaults

Phase 2: Prepare Files for Shared

For each file being migrated, apply these transformations:

2a. Fix Imports

2b. Strip @lingui

Replace all t tagged template literals with plain English strings:

// Before
t`[Image]`
t`invalid message type`
t`[Sticker: ${name}]`

// After
'[Image]'
'invalid message type'
`[Sticker: ${name}]`

The consuming app passes translated strings via props when needed. This follows the industry standard (shadcn/ui, Radix, MUI).

2c. Guard Browser APIs

If the file uses window, document, or navigator, add guards:

if (typeof window !== 'undefined') {
  // browser-only code
}

Files that are inherently browser-only should NOT be migrated.

2d. Handle ESM-only Dependencies

Some npm packages (e.g., unified, remark-*, devlop) are ESM-only and break Metro/Hermes on React Native.

Solution: Create a .native.ts companion file with a regex-based or simplified implementation that has the same API but no ESM-only imports. See quorum-shared/src/utils/markdownStripping.native.ts as a reference.

2e. Handle Platform-Specific Files

For components with .web.tsx / .native.tsx splits:

• Copy both platform files to shared
• tsup config handles platform-specific entry points
• Ensure .native.tsx files don't import web-only packages (react-tooltip, etc.)

Phase 3: Copy to quorum-shared

3a. Add Dependencies

If the migrated files need npm packages not yet in shared:

1. Check exact versions in d:/GitHub/Quilibrium/quorum-desktop/package.json
2. Add to d:/GitHub/Quilibrium/quorum-shared/package.json with matching versions
3. Run yarn install in quorum-shared
4. Verify build: yarn build

3b. Copy Files

Copy each prepared file to the appropriate location in shared:

3c. Handle Merge Conflicts with Existing Shared Code

If shared already has a simpler version of the same file (e.g., validation.ts, mentions.ts):

1. Compare both versions — desktop's is usually more complete
2. Replace shared's version with desktop's
3. Check if shared's version had any functions NOT in desktop's — append those to the new file
4. Rename any type/function that collides (e.g., NotificationSettings → SpaceNotificationSettings)

3d. Update Barrel Export

Add re-exports to the appropriate barrel file:

// src/utils/index.ts
export * from './newModule';

// For default exports (like dayjs):
export { default as dayjs } from './dayjs';

3e. Verify Build

cd d:/GitHub/Quilibrium/quorum-shared
yarn build

Expected: 0 errors. All 3 outputs generated (index.mjs, index.js, index.native.js).

Phase 4: Update quorum-desktop

4a. Update Imports

Find all files that import from the migrated local paths:

grep -r "from.*utils/<migrated-module>" d:/GitHub/Quilibrium/quorum-desktop/src/ --include="*.ts" --include="*.tsx" -l

Update each to import from @quilibrium/quorum-shared:

// Before
import { validateEmail } from '../utils/validation';

// After
import { validateEmail } from '@quilibrium/quorum-shared';

4b. Handle Partial Migrations

If only some functions from a file were migrated (e.g., channelUtils.ts):

• Keep the local file with non-migrated functions
• Add a re-export for the migrated function: export { findChannelByName } from '@quilibrium/quorum-shared'
• Update consumers to import from the local barrel or shared directly

4c. Delete Local Source Files

Delete the migrated .ts files from desktop. Keep:

• SCSS files (styles stay in the consuming app)
• Test files (update their imports, don't delete tests)
• Files with non-migrated functions (partially migrated)

4d. Update Test Files

Test files that imported from local paths need updated imports:

// Before
import { groupMessages } from '../../utils/messageGrouping';

// After
import { groupMessages } from '@quilibrium/quorum-shared';

Phase 5: Verify Everything

Run these checks in order:

5a. quorum-shared build

cd d:/GitHub/Quilibrium/quorum-shared && yarn build

5b. quorum-desktop web build

cd d:/GitHub/Quilibrium/quorum-desktop && yarn build

5c. quorum-desktop dev server

cd d:/GitHub/Quilibrium/quorum-desktop && yarn dev

Verify the app loads in browser — check for blank pages (ESM import failures are silent).

5d. Mobile compatibility (if applicable)

cd d:/GitHub/Quilibrium/quorum-desktop && yarn mobile

Check Metro bundles without errors. If it fails, look for ESM-only packages (Phase 2d).

5e. Check for DOM API leaks

grep -r "window\.\|document\.\|navigator\." d:/GitHub/Quilibrium/quorum-shared/src/ --include="*.ts" --include="*.tsx" | grep -v "typeof window" | grep -v "typeof document" | grep -v ".native."

5f. Run tests

cd d:/GitHub/Quilibrium/quorum-desktop && yarn test

Compare results with previous run — no NEW failures should be introduced.

Phase 6: Commit

On quorum-shared

Commit in this order:

1. Dependencies (if any new ones): package.json + yarn.lock
2. Source files: All new/modified files under src/
3. Fixes (if any arose during verification): Separate commits

On quorum-desktop

Commit in this order:

1. Import updates + file deletions: One atomic commit
2. Test import updates: Separate commit if significant

Known Gotchas

These are lessons learned from prior migrations. Check each one:

Before Merging PRs

These steps must happen before any migration PR is merged:

1. Switch link:../quorum-shared back to the published npm version in package.json
2. Publish @quilibrium/quorum-shared with a version bump
3. Run full build + smoke test with the published version
4. Verify mobile bundles with the published version

Last updated: 2026-03-18