Date Formatting
Guidelines for consistent date and time formatting across applications.
Critical Rule
Use centralized date utilities for consistency:
typescript
// ❌ AVOID - Inconsistent across locales/platforms
date.toLocaleDateString()
date.toLocaleString()
new Intl.DateTimeFormat().format(date)
// ✅ CORRECT - Use centralized utility
import { formatDate } from '@{scope}/shared/src/utils/dateUtils';
formatDate(date, { hideSeconds: true });
Quick Reference
| Function | Use Case | Example Output |
|---|---|---|
formatDate(date, options?) | Full date and time | 2024/01/15, 14:30 |
formatTime(date, options?) | Time only | 14:30:45 |
formatRelativeDate(date) | Relative display | Today, Yesterday |
formatDistanceToNow(date) | Time distance | 2 hours ago |
formatDateFns(date, format?) | Custom format | Based on template |
Common Patterns
Transaction History
typescript
import { formatDate } from '@{scope}/shared/src/utils/dateUtils';
// Hide year if current year, hide seconds
<Text>
{formatDate(item.createdAt, { hideTheYear: true, hideSeconds: true })}
</Text>
Custom Format
typescript
// Use format template
{formatDate(item.timestamp, { formatTemplate: 'yyyy-LL-dd HH:mm' })}
React Hook (for dynamic updates)
typescript
import { useFormatDate } from '@{scope}/kit/src/hooks/useFormatDate';
function MyComponent() {
const { formatDate } = useFormatDate();
return <Text>{formatDate(date, { hideSeconds: true })}</Text>;
}
Format Options
typescript
interface IFormatDateOptions {
hideYear?: boolean; // Always hide year
hideMonth?: boolean; // Always hide month
hideTheYear?: boolean; // Hide year if current year
hideTheMonth?: boolean; // Hide month if current month
hideTimeForever?: boolean; // Hide time portion
hideSeconds?: boolean; // Hide seconds (HH:mm)
formatTemplate?: string; // Custom date-fns format
}
Detailed Guide
For comprehensive date formatting rules and examples, see date-formatting.md.
Topics covered:
- •Core utilities for date formatting
- •Available formatting functions
- •Options reference and format templates
- •Common patterns for transactions, history, and relative time
- •React hooks for dynamic updates
- •Locale-aware formatting
- •Real-world examples
- •Troubleshooting
Key Files (Example Structure)
| Purpose | File Path |
|---|---|
| Core utilities | packages/shared/src/utils/dateUtils.ts |
| React hook | packages/kit/src/hooks/useFormatDate.ts |
| Locale mapping | packages/shared/src/locale/dateLocaleMap.ts |
Related Skills
- •
/i18n- Internationalization and locale handling - •
/coding-patterns- General coding patterns