Code Style

Import ordering

Imports follow a strict order, separated by blank lines:

// 1. Type-only imports
import type { Foo } from './types'

// 2. External packages
import { useState } from 'react'

// 3. Internal packages
import { hash } from '@xnet/crypto'

// 4. Local relative imports
import { helper } from './utils'

Naming conventions

Category	Convention	Example
Functions	camelCase, verb-first	createNode, verifySignature
Types	PascalCase	NodeStore, SyncStatus
Constants	SCREAMING_SNAKE	MAX_UPDATE_SIZE, DEFAULT_TTL
Classes	PascalCase	SpatialIndex, Viewport
Type parameters	Single uppercase	T, P
Unused parameters	Prefix with _	_event, _unused

TypeScript

• Strict mode enabled — no implicit any, strict null checks
• Prefer type over interface for object shapes
• Explicit return types on exported functions
• Template literal types for branded strings: `xnet://${string}/`
• No any without justification — use unknown instead

Exports

• Named exports only — no default exports
• Barrel files (index.ts) re-export from internal modules
• Export types inline: export { fn, type FnResult }
• Factory functions alongside classes: createFoo() next to class Foo

Comments

File-level JSDoc

/**
 * @xnet/sync - Unified sync primitives for xNet
 */

Section dividers

// ─── Section Name ────────────────────────────────────────

Function docs

/**
 * Create a signed envelope for a Yjs update.
 * @example
 * const envelope = signYjsUpdate(update, did, key, clientId)
 */

Error handling

• Return { valid: boolean, errors: [] } for validation — don’t throw
• Try-catch with type narrowing: err instanceof Error ? err : new Error(String(err))
• Early returns for edge cases
• Boolean returns for simple success/failure

React patterns

• Return typed objects from hooks (not tuples)
• Use refs for values accessed in callbacks (avoid stale closures)
• Always return cleanup functions from useEffect
• Debug logging via localStorage: localStorage.getItem('xnet:sync:debug')
• Prefer Tailwind over custom CSS