datetime-timezone

Name: datetime-timezone
Author: mjunaidca

26stars11forks

How to install datetime-timezone?

mjunaidca/mjs-agent-skills/datetime-timezone

$npx -y skills add mjunaidca/mjs-agent-skills --skill datetime-timezone

Installs into the current project.

Summary

Handle datetime and timezone conversions correctly across frontend, API, and database. Use this skill when working with datetime-local inputs, scheduling features, due dates, reminders, or any time-sensitive functionality. Covers the critical pitfall of browser datetime-local inp

Files · 1

View on GitHub

SKILL.md

1	# DateTime and Timezone Handling
2
3	Correctly handle datetime values across the full stack: browser → API → database → back to browser.
4
5	## When to Use
6
7	- Implementing due dates, reminders, or scheduling features
8	- Working with `datetime-local` HTML inputs
9	- Storing timestamps in PostgreSQL/databases
10	- Displaying times in user's local timezone
11	- Debugging "wrong time" issues
12
13	## The Golden Rule
14
15	Store UTC, Display Local
16
17	```
18	Browser (local) → Convert to UTC → API → Store UTC → Database
19	Database → Return UTC → API → Browser → Display in local
20	```
21
22	## Critical Pitfall: datetime-local Input
23
24	The HTML `<input type="datetime-local">` returns a string WITHOUT timezone info:
25
26	```html
27	<input type="datetime-local" value="2025-12-15T23:13">
28	```
29
30	This gives you `"2025-12-15T23:13"` - but is this UTC? Local time? The browser doesn't tell you.
31
32	### The Bug
33
34	```typescript
35	// WRONG - Backend interprets as UTC, but user entered local time!
36	const dueDate = "2025-12-15T23:13" // User in PKT (UTC+5)
37	await api.createTask({ due_date: dueDate })
38	// Backend stores as 23:13 UTC
39	// But user meant 23:13 PKT = 18:13 UTC
40	// Task is now 5 hours late!
41	```
42
43	### The Fix
44
45	```typescript
46	// CORRECT - Convert local datetime to UTC ISO string
47	function handleSubmit() {
48	let dueDateUTC: string \| undefined = undefined
49
50	if (dueDate) {
51	// datetime-local gives "2025-12-15T23:13" (local time, no TZ)
52	// new Date() interprets it in browser's local timezone
53	// toISOString() converts to UTC: "2025-12-15T18:13:00.000Z"
54	const localDate = new Date(dueDate)
55	dueDateUTC = localDate.toISOString()
56	}
57
58	await api.createTask({ due_date: dueDateUTC })
59	}
60	```
61
62	## Frontend Patterns (TypeScript/React)
63
64	### Converting datetime-local to UTC
65
66	```typescript
67	// Input: "2025-12-15T23:13" (from datetime-local)
68	// Output: "2025-12-15T18:13:00.000Z" (UTC ISO string)
69
70	function localToUTC(localDatetime: string): string {
71	const date = new Date(localDatetime)
72	return date.toISOString()
73	}
74	```
75
76	### Converting UTC to datetime-local (for editing)
77
78	```typescript
79	// Input: "2025-12-15T18:13:00Z" (UTC from API)
80	// Output: "2025-12-15T23:13" (local, for datetime-local input)
81
82	function utcToLocal(utcDatetime: string): string {
83	const date = new Date(utcDatetime)
84	// Format: YYYY-MM-DDTHH:MM (no seconds, no Z)
85	const year = date.getFullYear()
86	const month = String(date.getMonth() + 1).padStart(2, '0')
87	const day = String(date.getDate()).padStart(2, '0')
88	const hours = String(date.getHours()).padStart(2, '0')
89	const minutes = String(date.getMinutes()).padStart(2, '0')
90	return `${year}-${month}-${day}T${hours}:${minutes}`
91	}
92	```
93
94	### Full Form Example (React)
95
96	```tsx
97	"use client"
98
99	import { useState } from "react"
100
101	export function TaskForm() {
102	const [dueDate, setDueDate] = useState("") // Local datetime string
103
104	const handleSubmit = async (e: React.FormEvent) => {
105	e.preventDefault()
106
107	// Convert local to UTC for API
108	let dueDateUTC: string \| undefined
109	if (dueDate) {
110	dueDateUTC = new Date(dueDate).toISOString()
111	}
112
113	await api.createTask({
114	title: "My Task",
115	due_date: dueDateUTC, // UTC ISO string
116	})
117	}
118
119	return (
120	<form onSubmit={handleSubmit}>
121	<input
122	type="datetime-local"
123	value={dueDate}
124	onChange={(e) => setDueDate(e.target.value)}
125	/>
126	<button type="submit">Create</button>
127	</form>
128	)
129	}
130	```
131
132	### Editing Existing Task
133
134	```tsx
135	"use client"
136
137	import { useState, useEffect } from "react"
138
139	export function EditTaskForm({ task }: { task: Task }) {
140	const [dueDate, setDueDate] = useState("")
141
142	useEffect(() => {
143	// Convert UTC from API to local for input
144	if (task.due_date) {
145	setDueDate(utcToLocal(task.due_date))
146	}
147	}, [task])
148
149	const handleSubmit = async (e: React.FormEvent) => {
150	e.preventDefault()
151
152	// Convert back to UTC for API
153	const dueDateUTC = dueDate ? new Date(dueDate).toISOString() : undefined
154
155	await api.updateTask(task.id, { due_date: dueDateUTC })
156	}
157
158	return (
159	<input
160	type="datetime-local"
161	value={dueDate}
162	onChange={(e) => setDueDate(e.target.value)}
163	/>
164	)
165	}
166	```
167
168	## Backend Patterns (Python/FastAPI)
169
170	### Pydantic Model with Timezone Normalization
171
172	```python
173	from datetime import UTC, datetime
174	from pydantic import field_validator
175	from sqlmodel import SQLModel
176
177	class TaskCreate(SQLModel):
178	title: str
179	due_date: datetime \| None = None
180
181	@field_validator("due_date", mode="after")
182	@classmethod
183	def normalize_datetime(cls, v: datetime \| None) -> datetime \| None:
184	"""Convert timezone-aware to naive UTC for storage."""
185	if v

People who liked this also viewed

6 picks

Type

datetime-timezone

26stars11forks

View on GitHub

How to install datetime-timezone?

mjunaidca/mjs-agent-skills/datetime-timezone

$npx -y skills add mjunaidca/mjs-agent-skills --skill datetime-timezone

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# DateTime and Timezone Handling
2
3	Correctly handle datetime values across the full stack: browser → API → database → back to browser.
4
5	## When to Use
6
7	- Implementing due dates, reminders, or scheduling features
8	- Working with `datetime-local` HTML inputs
9	- Storing timestamps in PostgreSQL/databases
10	- Displaying times in user's local timezone
11	- Debugging "wrong time" issues
12
13	## The Golden Rule
14
15	Store UTC, Display Local
16
17	```
18	Browser (local) → Convert to UTC → API → Store UTC → Database
19	Database → Return UTC → API → Browser → Display in local
20	```
21
22	## Critical Pitfall: datetime-local Input
23
24	The HTML `<input type="datetime-local">` returns a string WITHOUT timezone info:
25
26	```html
27	<input type="datetime-local" value="2025-12-15T23:13">
28	```
29
30	This gives you `"2025-12-15T23:13"` - but is this UTC? Local time? The browser doesn't tell you.
31
32	### The Bug
33
34	```typescript
35	// WRONG - Backend interprets as UTC, but user entered local time!
36	const dueDate = "2025-12-15T23:13" // User in PKT (UTC+5)
37	await api.createTask({ due_date: dueDate })
38	// Backend stores as 23:13 UTC
39	// But user meant 23:13 PKT = 18:13 UTC
40	// Task is now 5 hours late!
41	```
42
43	### The Fix
44
45	```typescript
46	// CORRECT - Convert local datetime to UTC ISO string
47	function handleSubmit() {
48	let dueDateUTC: string \| undefined = undefined
49
50	if (dueDate) {
51	// datetime-local gives "2025-12-15T23:13" (local time, no TZ)
52	// new Date() interprets it in browser's local timezone
53	// toISOString() converts to UTC: "2025-12-15T18:13:00.000Z"
54	const localDate = new Date(dueDate)
55	dueDateUTC = localDate.toISOString()
56	}
57
58	await api.createTask({ due_date: dueDateUTC })
59	}
60	```
61
62	## Frontend Patterns (TypeScript/React)
63
64	### Converting datetime-local to UTC
65
66	```typescript
67	// Input: "2025-12-15T23:13" (from datetime-local)
68	// Output: "2025-12-15T18:13:00.000Z" (UTC ISO string)
69
70	function localToUTC(localDatetime: string): string {
71	const date = new Date(localDatetime)
72	return date.toISOString()
73	}
74	```
75
76	### Converting UTC to datetime-local (for editing)
77
78	```typescript
79	// Input: "2025-12-15T18:13:00Z" (UTC from API)
80	// Output: "2025-12-15T23:13" (local, for datetime-local input)
81
82	function utcToLocal(utcDatetime: string): string {
83	const date = new Date(utcDatetime)
84	// Format: YYYY-MM-DDTHH:MM (no seconds, no Z)
85	const year = date.getFullYear()
86	const month = String(date.getMonth() + 1).padStart(2, '0')
87	const day = String(date.getDate()).padStart(2, '0')
88	const hours = String(date.getHours()).padStart(2, '0')
89	const minutes = String(date.getMinutes()).padStart(2, '0')
90	return `${year}-${month}-${day}T${hours}:${minutes}`
91	}
92	```
93
94	### Full Form Example (React)
95
96	```tsx
97	"use client"
98
99	import { useState } from "react"
100
101	export function TaskForm() {
102	const [dueDate, setDueDate] = useState("") // Local datetime string
103
104	const handleSubmit = async (e: React.FormEvent) => {
105	e.preventDefault()
106
107	// Convert local to UTC for API
108	let dueDateUTC: string \| undefined
109	if (dueDate) {
110	dueDateUTC = new Date(dueDate).toISOString()
111	}
112
113	await api.createTask({
114	title: "My Task",
115	due_date: dueDateUTC, // UTC ISO string
116	})
117	}
118
119	return (
120	<form onSubmit={handleSubmit}>
121	<input
122	type="datetime-local"
123	value={dueDate}
124	onChange={(e) => setDueDate(e.target.value)}
125	/>
126	<button type="submit">Create</button>
127	</form>
128	)
129	}
130	```
131
132	### Editing Existing Task
133
134	```tsx
135	"use client"
136
137	import { useState, useEffect } from "react"
138
139	export function EditTaskForm({ task }: { task: Task }) {
140	const [dueDate, setDueDate] = useState("")
141
142	useEffect(() => {
143	// Convert UTC from API to local for input
144	if (task.due_date) {
145	setDueDate(utcToLocal(task.due_date))
146	}
147	}, [task])
148
149	const handleSubmit = async (e: React.FormEvent) => {
150	e.preventDefault()
151
152	// Convert back to UTC for API
153	const dueDateUTC = dueDate ? new Date(dueDate).toISOString() : undefined
154
155	await api.updateTask(task.id, { due_date: dueDateUTC })
156	}
157
158	return (
159	<input
160	type="datetime-local"
161	value={dueDate}
162	onChange={(e) => setDueDate(e.target.value)}
163	/>
164	)
165	}
166	```
167
168	## Backend Patterns (Python/FastAPI)
169
170	### Pydantic Model with Timezone Normalization
171
172	```python
173	from datetime import UTC, datetime
174	from pydantic import field_validator
175	from sqlmodel import SQLModel
176
177	class TaskCreate(SQLModel):
178	title: str
179	due_date: datetime \| None = None
180
181	@field_validator("due_date", mode="after")
182	@classmethod
183	def normalize_datetime(cls, v: datetime \| None) -> datetime \| None:
184	"""Convert timezone-aware to naive UTC for storage."""
185	if v

People who liked this also viewed

6 picks

Type