Feat; Add KOITO_DATE_FORMAT, KOITO_CLOCK_FORMAT and KOITO_WEEK_START configuration options

client/api/api.ts

@@ -436,6 +436,9 @@ type ApiError = {
 };
 type Config = {
   default_theme: string;
+  date_format: string;
+  clock_format: string;
+  week_start: string;
 };
 type NowPlaying = {
   currently_playing: boolean;

client/app/components/ActivityGrid.tsx

@@ -1,4 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
+import { useAppContext } from "~/providers/AppProvider";
+import { formatDate } from "~/utils/utils";
 import Popup from "./Popup";
 import {
   apiFetch,
@@ -55,6 +57,7 @@ export default function ActivityGrid({
     queryFn: () => getActivity(args),
   });
 
+  const { dateFormat, weekStart } = useAppContext();
   const width = useWindowWidth();
 
   if (isPending) {
@@ -90,20 +93,28 @@ export default function ActivityGrid({
     listenMap.set(key, item.listens);
   }
 
-  let firstDay = 1;
-  try {
-    // This doesn't work in Firefox
-    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getWeekInfo
-    firstDay = new Intl.Locale(navigator.language).getWeekInfo().firstDay;
-  } catch (err) {
-    console.log(err);
+  // Map day name → Intl firstDay integer (1=Mon … 7=Sun)
+  const weekStartMap: Record<string, number> = {
+    Monday: 1, Tuesday: 2, Wednesday: 3, Thursday: 4,
+    Friday: 5, Saturday: 6, Sunday: 7,
+  };
+  let firstDay = weekStartMap[weekStart] ?? 0;
+  if (!firstDay) {
+    firstDay = 1;
+    try {
+      // This doesn't work in Firefox
+      // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getWeekInfo
+      firstDay = new Intl.Locale(navigator.language).getWeekInfo().firstDay;
+    } catch (err) {
+      console.log(err);
+    }
   }
 
-  // Align the grid to calendar weeks (Monday = row 0, Sunday = row 6).
+  // Align the grid to calendar weeks.
   // Column 0 is the oldest week; the last column is the current (partial) week.
   const today = new Date();
   today.setHours(0, 0, 0, 0);
-  const daysSinceMonday = (today.getDay() + (7 - firstDay)) % 7; // Mon=0 … Sun=6
+  const daysSinceMonday = (today.getDay() + (7 - firstDay)) % 7;
   const gridStart = new Date(today);
   gridStart.setDate(
     gridStart.getDate() - daysSinceMonday - (NUM_WEEKS - 1) * 7,
@@ -130,10 +141,10 @@ export default function ActivityGrid({
   const CELL_H = "h-[9px] sm:h-[10px]";
   const CELL_GAP = "gap-[2px] md:gap-[3px]";
   const CELL_RADIUS = "rounded-[2px]";
-  const DAY_LABELS =
-    firstDay == 1
-      ? ["Mon", "", "Wed", "", "Fri", "", "Sun"]
-      : ["Sun", "", "Tue", "", "Thu", "", "Sat"];
+  const ALL_DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+  const DAY_LABELS = Array.from({ length: 7 }, (_, i) =>
+    i % 2 === 0 ? ALL_DAYS[(firstDay - 1 + i) % 7] : "",
+  );
 
   return (
     <div className="flex flex-col items-start">
@@ -165,7 +176,7 @@ export default function ActivityGrid({
                     position="top"
                     space={12}
                     extraClasses="left-2"
-                    inner={`${cell.date.toLocaleDateString()} ${
+                    inner={`${formatDate(cell.date, dateFormat)} ${
                       cell.listens
                     } plays`}
                   >

client/app/components/ListensTable.tsx

@@ -21,7 +21,7 @@ export default function ListensTable({
   hideArtists,
   onDelete,
 }: ListensTableProps) {
-  const { user } = useAppContext();
+  const { user, dateFormat, clockFormat } = useAppContext();
   const imgColSizeClasses = "py-3 min-w-8 sm:min-w-11";
   const imgSize = 32;
   const timeColClasses = "text-(--color-fg-tertiary) pr-2 sm:pr-4 sm:text-sm";
@@ -99,7 +99,7 @@ export default function ListensTable({
               className={`text-end whitespace-nowrap ${timeColClasses}`}
               title={new Date(item.time).toString()}
             >
-              {timeSince(new Date(item.time))}
+              {timeSince(new Date(item.time), dateFormat, clockFormat)}
             </td>
             <td className="hidden sm:table">
               <button

client/app/providers/AppProvider.tsx

@@ -12,6 +12,9 @@ interface AppContextType {
   configurableHomeActivity: boolean;
   homeItems: number;
   defaultTheme: string;
+  dateFormat: string;
+  clockFormat: string;
+  weekStart: string;
   currentVersion: string;
   updateAvailable: boolean;
   firstActivity: Date | undefined;
@@ -38,6 +41,9 @@ export const AppProvider = ({ children }: { children: React.ReactNode }) => {
   const [configurableHomeActivity, setConfigurableHomeActivity] =
     useState<boolean>(false);
   const [homeItems, setHomeItems] = useState<number>(0);
+  const [dateFormat, setDateFormat] = useState<string>("");
+  const [clockFormat, setClockFormat] = useState<string>("");
+  const [weekStart, setWeekStart] = useState<string>("");
 
   const setUsername = (value: string) => {
     if (!user) {
@@ -69,6 +75,9 @@ export const AppProvider = ({ children }: { children: React.ReactNode }) => {
       } else {
         setDefaultTheme("yuu");
       }
+      setDateFormat(cfg.date_format ?? "");
+      setClockFormat(cfg.clock_format ?? "");
+      setWeekStart(cfg.week_start ?? "");
     });
 
     fetch("/apis/web/v1/first-activity")
@@ -100,6 +109,9 @@ export const AppProvider = ({ children }: { children: React.ReactNode }) => {
     configurableHomeActivity,
     homeItems,
     defaultTheme,
+    dateFormat,
+    clockFormat,
+    weekStart,
     currentVersion,
     updateAvailable,
     firstActivity,

client/app/routes/MediaItems/MediaLayout.tsx

@@ -10,7 +10,7 @@ import DeleteModal from "~/components/modals/DeleteModal";
 import EditModal from "~/components/modals/EditModal/EditModal";
 import AddListenModal from "~/components/modals/AddListenModal";
 import MbzIcon from "~/components/icons/MbzIcon";
-import { timeListenedString } from "~/utils/utils";
+import { timeListenedString, formatDate, formatDateTime } from "~/utils/utils";
 import { Link } from "react-router";
 import useWindowWidth from "~/hooks/useWindowWidth";
 
@@ -48,7 +48,7 @@ export default function MediaLayout(props: Props) {
   const [imageModalOpen, setImageModalOpen] = useState(false);
   const [renameModalOpen, setRenameModalOpen] = useState(false);
   const [addListenModalOpen, setAddListenModalOpen] = useState(false);
-  const { user } = useAppContext();
+  const { user, dateFormat, clockFormat } = useAppContext();
 
   useEffect(() => {
     average(props.img.xs, { amount: 1 }).then((color) => {
@@ -129,9 +129,9 @@ export default function MediaLayout(props: Props) {
                 </p>
               )}
               {props.firstListen > 0 && (
-                <p title={new Date(props.firstListen * 1000).toLocaleString()}>
+                <p title={formatDateTime(new Date(props.firstListen * 1000), dateFormat, clockFormat)}>
                   Listening since{" "}
-                  {new Date(props.firstListen * 1000).toLocaleDateString()}
+                  {formatDate(new Date(props.firstListen * 1000), dateFormat)}
                 </p>
               )}
             </div>

client/app/utils/utils.ts

@@ -28,7 +28,22 @@ const getRewindParams = (): { month: number; year: number } => {
   }
 };
 
-function timeSince(date: Date) {
+function formatDate(date: Date, dateFormat: string = ""): string {
+  if (!dateFormat) return date.toLocaleDateString();
+  const dd = String(date.getDate()).padStart(2, "0");
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const yyyy = String(date.getFullYear());
+  return dateFormat.replace("DD", dd).replace("MM", mm).replace("YYYY", yyyy);
+}
+
+function formatDateTime(date: Date, dateFormat: string = "", clockFormat: string = ""): string {
+  const timeOptions: Intl.DateTimeFormatOptions = { timeStyle: "short" };
+  if (clockFormat === "12h") timeOptions.hour12 = true;
+  if (clockFormat === "24h") timeOptions.hour12 = false;
+  return `${formatDate(date, dateFormat)} ${date.toLocaleTimeString([], timeOptions)}`;
+}
+
+function timeSince(date: Date, dateFormat: string = "", clockFormat: string = "") {
   const now = new Date();
   const seconds = Math.floor((now.getTime() - date.getTime()) / 1000);
 
@@ -42,18 +57,8 @@ function timeSince(date: Date) {
     { label: "second", seconds: 1 },
   ];
 
-  // 1 day
   if (seconds > 86400) {
-    const dateString = date.toLocaleDateString([], {
-      month: "numeric",
-      year: "2-digit",
-      day: "numeric",
-    });
-
-    const timeString = date.toLocaleTimeString([], {
-      timeStyle: "short",
-    });
-    return `${dateString} ${timeString}`;
+    return formatDateTime(date, dateFormat, clockFormat);
   }
 
   for (const interval of intervals) {
@@ -66,7 +71,7 @@ function timeSince(date: Date) {
   return "just now";
 }
 
-export { timeSince };
+export { formatDate, formatDateTime, timeSince };
 
 type hsl = {
   h: number;

docs/src/content/docs/reference/configuration.md

@@ -26,6 +26,23 @@ If the environment variable is defined without **and** with the suffix at the sa
 - Default: `yuu`
 - Description: The lowercase name of the default theme to be used by the client. Overridden if a user picks a theme in the theme switcher.
 
+##### KOITO_DATE_FORMAT
+
+- Default: Browser locale
+- Description: The date format to use when displaying dates. Must use the `DD`, `MM`, and `YYYY` tokens each exactly once, separated by `/`, `-`, or `.`. When not set, the browser locale determines the format.
+- Example: `DD/MM/YYYY` produces `21/04/2026`
+
+##### KOITO_CLOCK_FORMAT
+
+- Default: Browser locale
+- Description: The clock format to use when displaying times. Accepted values are `12h` and `24h`. When not set, the browser locale determines the format.
+
+##### KOITO_WEEK_START
+
+- Default: Browser locale
+- Description: The first day of the week to use in the activity grid. Accepted values are `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, and `Sunday`. When not set, the browser locale determines the first day (falls back to Monday in Firefox).
+- Example: `Monday` for most European locales
+
 ##### KOITO_LOGIN_GATE
 
 - Default: `false`

engine/handlers/server_cfg.go

@@ -9,10 +9,18 @@ import (
 
 type ServerConfig struct {
 	DefaultTheme string `json:"default_theme"`
+	DateFormat   string `json:"date_format"`
+	ClockFormat  string `json:"clock_format"`
+	WeekStart    string `json:"week_start"`
 }
 
 func GetCfgHandler() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		utils.WriteJSON(w, http.StatusOK, ServerConfig{DefaultTheme: cfg.DefaultTheme()})
+		utils.WriteJSON(w, http.StatusOK, ServerConfig{
+			DefaultTheme: cfg.DefaultTheme(),
+			DateFormat:   cfg.DateFormat(),
+			ClockFormat:  cfg.ClockFormat(),
+			WeekStart:    cfg.WeekStart(),
+		})
 	}
 }

internal/cfg/cfg.go

@@ -50,6 +50,9 @@ const (
 	ARTIST_SEPARATORS_ENV          = "KOITO_ARTIST_SEPARATORS_REGEX"
 	LOGIN_GATE_ENV                 = "KOITO_LOGIN_GATE"
 	FORCE_TZ                       = "KOITO_FORCE_TZ"
+	DATE_FORMAT_ENV                = "KOITO_DATE_FORMAT"
+	CLOCK_FORMAT_ENV               = "KOITO_CLOCK_FORMAT"
+	WEEK_START_ENV                 = "KOITO_WEEK_START"
 )
 
 type config struct {
@@ -89,6 +92,9 @@ type config struct {
 	artistSeparators       []*regexp.Regexp
 	loginGate              bool
 	forceTZ                *time.Location
+	dateFormat             string
+	clockFormat            string
+	weekStart              string
 }
 
 var (
@@ -192,6 +198,34 @@ func loadConfig(getenv func(string) string, version string) (*config, error) {
 
 	cfg.defaultTheme = getenv(DEFAULT_THEME_ENV)
 
+	rawDateFormat := getenv(DATE_FORMAT_ENV)
+	if rawDateFormat != "" {
+		validFormat := regexp.MustCompile(`^(DD|MM|YYYY)([-/.](DD|MM|YYYY)){2}$`)
+		if !validFormat.MatchString(rawDateFormat) ||
+			!strings.Contains(rawDateFormat, "DD") ||
+			!strings.Contains(rawDateFormat, "MM") ||
+			!strings.Contains(rawDateFormat, "YYYY") {
+			return nil, fmt.Errorf("loadConfig: %s must use DD, MM, and YYYY tokens with a single / - or . separator (e.g. DD/MM/YYYY)", DATE_FORMAT_ENV)
+		}
+	}
+	cfg.dateFormat = rawDateFormat
+
+	rawClockFormat := getenv(CLOCK_FORMAT_ENV)
+	if rawClockFormat != "" && rawClockFormat != "12h" && rawClockFormat != "24h" {
+		return nil, fmt.Errorf("loadConfig: %s must be either '12h' or '24h'", CLOCK_FORMAT_ENV)
+	}
+	cfg.clockFormat = rawClockFormat
+
+	validWeekDays := map[string]bool{
+		"Monday": true, "Tuesday": true, "Wednesday": true, "Thursday": true,
+		"Friday": true, "Saturday": true, "Sunday": true,
+	}
+	rawWeekStart := getenv(WEEK_START_ENV)
+	if rawWeekStart != "" && !validWeekDays[rawWeekStart] {
+		return nil, fmt.Errorf("loadConfig: %s must be one of: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday", WEEK_START_ENV)
+	}
+	cfg.weekStart = rawWeekStart
+
 	cfg.configDir = getenv(CONFIG_DIR_ENV)
 	if cfg.configDir == "" {
 		cfg.configDir = "/etc/koito"

internal/cfg/getters.go

@@ -96,6 +96,24 @@ func DefaultTheme() string {
 	return globalConfig.defaultTheme
 }
 
+func DateFormat() string {
+	lock.RLock()
+	defer lock.RUnlock()
+	return globalConfig.dateFormat
+}
+
+func ClockFormat() string {
+	lock.RLock()
+	defer lock.RUnlock()
+	return globalConfig.clockFormat
+}
+
+func WeekStart() string {
+	lock.RLock()
+	defer lock.RUnlock()
+	return globalConfig.weekStart
+}
+
 func DeezerDisabled() bool {
 	lock.RLock()
 	defer lock.RUnlock()