datetime-timezone_skill
- Python
19
GitHub Stars
1
Bundled Files
2 months ago
Catalog Refreshed
4 months ago
First Indexed
Readme & install
Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.
Installation
Preview and clipboard use veilstrat where the catalogue uses aiagentskills.
npx veilstrat add skill mjunaidca/mjs-agent-skills --skill datetime-timezone- skill.md9.6 KB
Overview
This skill teaches precise datetime and timezone handling across frontend, API, and database layers. It focuses on the critical pitfall that HTML datetime-local inputs lack timezone information and provides concrete conversion patterns so systems store UTC and present local time correctly.
How this skill works
It inspects the data flow: browser datetime-local input → convert to UTC ISO for API → normalize and store as naive UTC in the database → return UTC ISO to clients → convert to local for display or editing. The skill includes frontend helpers (localToUTC, utcToLocal), backend validators to normalize timezone-aware datetimes to naive UTC, and debugging/test patterns to verify offsets.
When to use it
- Building due dates, reminders, scheduling, or calendar features
- Handling HTML <input type="datetime-local"> values in forms
- Storing and querying timestamps in PostgreSQL or other databases
- Displaying timestamps in the user's local timezone
- Investigating 'wrong time' bugs across frontend/backend
Best practices
- Always convert browser local datetimes to UTC ISO (new Date(value).toISOString()) before sending to the API
- Normalize incoming datetimes in the backend to naive UTC for storage (convert to UTC and strip tzinfo)
- Store timestamps as naive UTC (TIMESTAMP) in the database and avoid TIMESTAMP WITH TIME ZONE for this pattern
- Serialize API responses as UTC ISO strings (with Z) and convert to local on the client for display
- Log datetime values at each step and include the browser timezone when debugging
Example use cases
- A task manager: user picks a deadline with datetime-local, convert to UTC for API and store in DB
- An events app: list events in user locale while storing canonical UTC times for all participants
- Editing scheduled items: convert UTC from API to datetime-local format for the form and back to UTC on save
- Automated reminders: compare normalized naive UTC datetimes server-side to trigger notifications
- Tests that mock browser timezone to assert correct local->UTC conversions
FAQ
datetime-local lacks timezone info and represents local time. Converting to UTC preserves the intended instant across timezones so the backend stores the exact moment the user selected.
Should I store timestamps with or without timezone in the database?
Store naive UTC (no timezone). Normalize incoming values to UTC and strip tzinfo so queries and comparisons are consistent across environments.
How do I show a stored UTC timestamp to users in their timezone?
Return UTC ISO from the API and convert on the client with new Date(utcString).toLocaleString() or a formatting library for localized display.
