jadwal-sholat: Instructions file for Codex

Repository guide

Project structure

• apps/web is the website: Astro 7 with React islands, built as static files for Cloudflare Pages. See apps/web/AGENTS.md.
• apps/mobile is the Android app (Expo SDK 58, Expo Router, NativeWind v4 + React Native Reusables). See apps/mobile/AGENTS.md.
• packages/core holds framework-free domain code shared by the website and the Android app: API schemas and URL builders, prayer logic, the adzan schedule, dates, share links, Qur'an and puasa helpers, and bundled static data. It must never import React, React Query or zustand.
• Both apps pin the same react, react-dom, @types/react and @types/react-dom: the versions the Expo SDK in apps/mobile requires. A fresh install (Cloudflare Pages, EAS) hoists one copy per package for the whole workspace, so two versions mix type definitions and can load two Reacts. Bump them together.
• packages/typescript-config contains the shared TypeScript configs.
• static/docs contains README screenshots.
• Run workspace commands from the repository root unless a command says otherwise.

Commands

• Install dependencies: bun install
• Website: bun run dev:web (http://localhost:4321), bun run build:web (static output in apps/web/dist), bun run test:web (Cypress against bun run preview running in apps/web), type-check with cd apps/web && bun run check.
• Core tests and types: bun run test:core, bun run typecheck:core
• Android app: bun run dev:mobile (Metro for Expo Go or a development build), bun run typecheck:mobile, bun run build:android (preview APK on EAS). Native code compiles on EAS only; don't run Gradle or expo run:android locally.

The website build fetches the 114 surahs and the hadith book list from the public APIs, so it needs network access. Builds are memory-heavy: stop dev servers before building, and run one build at a time.

Implementation conventions (website)

• Use TypeScript, Astro pages with React islands, Tailwind CSS v4, shadcn/ui (radix-nova style), and ReUI.
• Prefer shared components in src/components/ui (shadcn) and src/components/reui (ReUI) over custom interactive elements. Tables use the ReUI data grid, modals use Dialog, toasts use sonner.
• Install components from apps/web with bunx --bun shadcn@latest add <name> --yes (ReUI items as @reui/<name>). The CLI writes import { cn } from "cn" and adds a cn package: change the imports to @/lib/utils/cn and run bun remove cn.
• Do not restyle installed components (radius, height, padding, shadow); use their size and variant props, and change the look through the theme tokens in src/styles/global.css.
• Every page renders BaseLayout (src/layouts/BaseLayout.astro); its content uses PageShell and PageHeader from src/components/common/page-shell.tsx. The site is a companion app, not a dashboard, so it uses two layouts:
  • Glance pages (homepage schedule, city schedules, Puasa Sunnah): <PageShell>. The homepage leads with the next prayer as plain type and keeps a Frame only around the month data grid; Puasa Sunnah keeps its Frame and data grid.
  • Reading pages (Qur'an, named ayat, hadith, Asma'ul Husna): no frames around content; separate items with plain bordered rows and generous spacing. List pages use the default site width and flow their rows into columns from md up (grid md:grid-cols-2, lg:grid-cols-3 for short rows like surahs); in a grid give each row border-b and the list border-t, because divide-y breaks across columns; detail pages (a surah, a hadith) use <PageShell width="reading">, a centered 768px column with a centered header (PageHeader align="center" or the surah's mushaf-style header).
• Widths: the top bar and every PageShell share one site width (max-w-5xl), so page edges line up; only detail pages narrow to the reading column. Don't add page-level max-w-* elsewhere.
• Navigation is a top bar with the five sections from md up and a bottom tab bar below md (src/components/layout); there is no sidebar and there are no breadcrumbs. On phones, detail pages show a back link in the top bar. PageShell reserves pb-24 for the bar on mobile.
• Design for desktop as well as phones: use the width for columns or a richer view (the Puasa Sunnah month calendar) instead of stretching phone rows. SearchBar focuses on / and shows the hint from md up.
• Share detail content with ShareButton from src/components/common/share-button.tsx (links built by getShareLinks in src/lib/helpers/share-links.ts, absolute URLs from SITE_URL). Ayah links use the #ayat-N anchors.
• Give every data region a Skeleton loading state, an Empty state with one action, and an inline Alert error with a retry.
• Fetch with getData from src/lib/utils/get-data.ts (native fetch); in islands use useFetch, which accepts build-time initialData and skips the request while its URL is "".
• Read the current time with the useNow() hook and format it with getDateParts() from src/lib/utils/date-parts.ts. Never compute dates at module level or during the build: static pages would bake in the build date, and open tabs go stale after midnight.
• Read API URLs from src/lib/utils/public-env.ts. The browser calls the APIs directly, except puasa, which goes through the /api/sunnah-fasting proxy in public/_worker.js.
• Pass only the fields an island renders: island props are serialized into the page's HTML (the surah page trims the API response).
• Keep mobile styles as the default; add larger-screen behavior with responsive variants.
• Preserve one <main> landmark, a logical heading hierarchy, visible focus states, keyboard behavior, and accessible names for every control.
• Keep mobile form text at text-base; use sm:text-sm only above the mobile breakpoint.
• Use arabic-font and lang="ar" for Arabic source text. The LPMQ font is defined in src/styles/global.css and served from public/fonts. Size Arabic text with [--arabic-size:<rem>], never a text-* class, so the reader's Arabic size setting applies.
• Follow the all-ages profile in apps/web/DESIGN.md: the root text scale (body text-sm renders at about 16px), a visible word beside every icon in a button, default-size actions, and plain words beside jargon.
• Respect prefers-reduced-motion; do not add unconditional motion or smooth scrolling. Use CSS (tw-animate-css utilities) for motion rather than an animation library.
• Write interface copy in clear Indonesian and use sentence case.