1k-date-formatting
Guides proper date and time formatting in OneKey app. Use when displaying dates/times in UI, formatting timestamps, or when dates need to follow app locale settings. Date, time, locale, formatDate, dateUtils.
Installation
Details
Usage
After installing, this skill will be available to your AI coding assistant.
Verify installation:
skills listSkill Instructions
name: 1k-date-formatting description: Guides proper date and time formatting in OneKey app. Use when displaying dates/times in UI, formatting timestamps, or when dates need to follow app locale settings. Date, time, locale, formatDate, dateUtils.
Date Formatting Skill
This skill ensures consistent date and time formatting across the OneKey app, respecting user locale settings.
Usage
Use this skill when:
- Displaying dates or times in UI components
- Formatting timestamps from API responses
- Ensuring dates follow the app's language/locale settings
- Converting date strings for display
Core Rules
NEVER use native JavaScript date methods
// ❌ FORBIDDEN - Does not respect app settings
date.toLocaleDateString()
date.toLocaleString()
date.toISOString()
new Intl.DateTimeFormat().format(date)
ALWAYS use OneKey's date utilities
// ✅ CORRECT - Follows app locale settings
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
formatDate(date, { hideSeconds: true });
Available Functions
From @onekeyhq/shared/src/utils/dateUtils
| Function | Description | 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, 2024/01/15 |
formatDistanceToNow(date) | Time distance | 2 days ago, 5 minutes ago |
formatDateFns(date, format?) | Custom format | Based on format template |
Options Reference
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 instead of HH:mm:ss)
formatTemplate?: string; // Custom date-fns format template
}
Format Templates
Common date-fns format tokens:
| Token | Description | Example |
|---|---|---|
yyyy | 4-digit year | 2024 |
LL | 2-digit month | 01 |
dd | 2-digit day | 15 |
HH | 24-hour hours | 14 |
mm | Minutes | 30 |
ss | Seconds | 45 |
PPP | Full date | January 15, 2024 |
Common Patterns
Transaction/History Lists
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
// Standard format, hide seconds
<SizableText>{formatDate(item.createdAt, { hideSeconds: true })}</SizableText>
Smart Year Display
// Hide year if it's the current year
<SizableText>
{formatDate(item.date, { hideTheYear: true, hideSeconds: true })}
</SizableText>
Custom Format
// Custom format template
<SizableText>
{formatDate(item.timestamp, { formatTemplate: 'yyyy-LL-dd HH:mm' })}
</SizableText>
Relative Time
import { formatDistanceToNow } from '@onekeyhq/shared/src/utils/dateUtils';
// "2 hours ago", "5 minutes ago"
<SizableText>{formatDistanceToNow(item.updatedAt)}</SizableText>
React Hook (for dynamic updates)
import useFormatDate from '@onekeyhq/kit/src/hooks/useFormatDate';
function MyComponent() {
const { formatDate, formatDistanceToNow } = useFormatDate();
return (
<SizableText>{formatDate(date, { hideSeconds: true })}</SizableText>
);
}
Locale-Aware Format
The date utilities automatically detect the app locale and adjust format:
// Automatically uses correct format based on locale:
// 'en-US' → 'LL/dd/yyyy, HH:mm:ss' (01/15/2024)
// 'zh-CN' → 'yyyy/LL/dd, HH:mm:ss' (2024/01/15)
// 'de' → 'LL/dd/yyyy, HH:mm:ss'
Real-World Examples
Example 1: ReferFriends List
// File: packages/kit/src/views/ReferFriends/pages/YourReferred/index.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
<SizableText size="$bodyMd" color="$textSubdued">
{item.createdAt
? formatDate(item.createdAt, { formatTemplate: 'yyyy-LL-dd HH:mm' })
: ''}
</SizableText>
Example 2: Transaction History
// File: packages/kit/src/components/TxHistoryListView/index.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
formatDate(new Date(date), {
hideTheYear: true,
hideSeconds: true,
})
Example 3: Redemption History
// File: packages/kit/src/views/Redemption/pages/RedemptionHistory.tsx
import { formatDate } from '@onekeyhq/shared/src/utils/dateUtils';
<SizableText size="$bodyMd" color="$textSubdued">
{formatDate(item.redeemedAt, { hideSeconds: true })}
</SizableText>
Key Files
| Purpose | File Path |
|---|---|
| Core utilities | packages/shared/src/utils/dateUtils.ts |
| React hook | packages/kit/src/hooks/useFormatDate.ts |
| Locale hook | packages/kit/src/hooks/useLocaleVariant.ts |
| Locale mapping | packages/shared/src/locale/dateLocaleMap.ts |
| App locale | packages/shared/src/locale/appLocale.ts |
Troubleshooting
Date shows wrong locale
Ensure you're using @onekeyhq/shared/src/utils/dateUtils instead of native methods. The utility automatically reads from appLocale.getLocale().
Need to update when locale changes
Use the useFormatDate hook in React components for reactive updates:
import useFormatDate from '@onekeyhq/kit/src/hooks/useFormatDate';
const { formatDate } = useFormatDate();
// Will re-render when locale changes
Custom format not working
Ensure your format template uses valid date-fns tokens. Common mistake: using MM (month with leading zero for parsing) instead of LL (month with leading zero for formatting).
More by OneKeyHQ
View allFilters specific errors from Sentry reporting in this OneKey monorepo. Use when needing to ignore/suppress/filter Sentry errors, add error exclusions, or stop certain errors from being reported. Handles platform-specific filtering (desktop/mobile/web/extension).
Helps fix ESLint errors and warnings in the OneKey codebase. Use when running yarn lint and encountering warnings, cleaning up code before committing, or fixing spellcheck, unused variable, or other ESLint warnings.
Guide for adding new blockchain chains to OneKey. Use when implementing new chain support, adding blockchain protocols, or understanding chain architecture. Triggers on chain, blockchain, protocol, network, coin, token, add chain, new chain.
Creates test version branches for testing app upgrade functionality. Use when preparing upgrade test builds, testing version migration, or when the user mentions test version, 9005.x.x version numbers, upgrade testing, or version upgrade QA. Automates branch creation, version bumping, and build number hardcoding for upgrade flow verification.