Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Public Site and Docs
The site/ workspace is the project's public website: a marketing home page and the user and self-hosting documentation. It is served at https://twiligent.ujjwal.fyi from the Cloudflare Pages project twiligent-site. The app itself runs at https://app.twiligent.ujjwal.fyi (see docs/architecture/frontend/).
The site is static. It makes no API calls, needs no secrets and shares no code with the app at runtime. Self-hosters do not need it to run Twiligent; it exists so the project has one public home and one copy of the docs. The decision is recorded in ADR-035 in DECISIONS.md.
Stack
| Concern | Library | Version |
|---|---|---|
| Language | TypeScript (strict) |
6.0 |
| Framework | React | 19 |
| Router | React Router (react-router) |
7 |
| Build tool | Vite | 7 |
| Styling | Tailwind CSS (@tailwindcss/vite) |
4 |
| Animation | motion | 14 |
| Docs pages | MDX (@mdx-js/rollup, @mdx-js/react) with remark-gfm |
3 |
| Code highlighting | Shiki (@shikijs/rehype), at build time |
4 |
| Docs search | MiniSearch | 7 |
| Icons | Solar (@iconify-json/solar), generated into one file |
- |
| Fonts | Sora, Manrope, JetBrains Mono (self-hosted from public/fonts) |
- |
The site does not use shadcn/ui, next-themes or Lucide; those belong to the app.
Folder Map
site/
index.html Meta tags, favicons, font preloads, the inline script that opens the app for a signed-in visitor
on the home page, and the inline script that sets data-theme before paint
vite.config.ts MDX (before the React plugin), React, Tailwind, docsPlugin, notFoundPage; @ alias to src/
build/
docsPlugin.ts Vite plugin: search index as virtual:docs-search, sitemap.xml and llms.txt in closeBundle
genIcons.ts Writes src/components/icons.tsx from @iconify-json/solar (npm run icons --workspace site)
notFoundPage.ts Vite plugin: copies dist/index.html to dist/404.html, so unknown paths get a real 404 status
content/docs/ One .mdx file per docs page; folders match the URL (self-host/redis.mdx is /docs/self-host/redis)
public/
_redirects 301s from the app's old paths to app.twiligent.ujjwal.fyi, and the docs routes rewritten to / (the home page's index.html)
robots.txt Allows every crawler; points at the sitemap
brand/ Logos, favicon, app icons and the share image, copied from the brand kit
fonts/ Latin woff2 files for the three brand families
src/
main.tsx Entry point: RouterProvider inside StrictMode
router.tsx Route table (see Routing)
index.css Fonts, brand palette, light and dark tokens, type styles, motion
pages/
Home.tsx Hero; everything below it is HomeBelow, loaded lazily
HomeBelow.tsx The home page sections in order
NotFound.tsx Marketing 404
components/
MarketingLayout.tsx Skip link, Navbar, page, Footer
Navbar.tsx, Footer.tsx, navLinks.ts, Pill.tsx, ThemeToggle.tsx, MotionToggle.tsx, ScrollManager.tsx
brand.tsx Logo, Mark, RibbonCrop, FoldBand (the brand graphics)
marks.tsx Hand-written SVG logos for YouTube, Instagram and GitHub
icons.tsx Generated Solar icons; never edited by hand
sections/ Home page sections: Story, Platforms, Faq, and the shared blocks (SectionHeader, FeatureSection, BentoCard, CtaBand)
mockups/ Product previews drawn in React (see Mockups and Motion): OverviewWindow, AnalyticsCard,
ScheduleCard, AreaChart, Cursor, Typed, CountUp, kit, sample, platforms; bento/ holds the
grid cards (Frame and one file per card)
docs/
DocsLayout.tsx Top bar with search, tabs, sidebar drawer on phones, page outlet
DocPage.tsx Loads one MDX page, sets its meta, shows Suggest edits, Raise issue and previous and next links
DocsSidebar.tsx Groups and pages of the current tab
nav.ts Tabs, groups and pages: the single source for docs navigation
Search.tsx Ctrl K or Cmd K search over the build-time index
searchShared.ts SearchDocument, the MiniSearch options and slugify(), shared by the plugin and the browser
Toc.tsx "On this page" outline of the h2 and h3 headings
mdx.tsx Heading, DocLink, CodeBlock, InlineCode, Callout, Steps, Step, Cards, Card, Badge
mdxComponents.tsx MDX_COMPONENTS: maps Markdown elements and the custom tags to the components above
virtual.d.ts Types the virtual:docs-search module
hooks/ useAutoplay, useElementSize, useMediaQuery, usePrefersReducedMotion, useStillMotion
lib/
chart.ts Chart geometry: seriesRange, chartPoints, smoothPath (monotone cubic), areaPath
format.ts formatNumber(): 84,213, 18.4K, 5.2%
links.ts App, GitHub, edit, issue, changelog, licence and privacy URLs
seo.ts usePageMeta(): title, description, canonical URL, Open Graph and Twitter tags
theme.ts useTheme(): reads and toggles data-theme and saves the choice
motion.ts useMotionPaused(): the Pause animations choice, kept in data-motion and localStorage
motionPreference.ts isPausedValue(): reads the stored choice (pure, tested)
cn.ts Class name joiner
tests/ Node tests in docs/ and lib/ (see Tests)
Routing
src/router.tsx uses createBrowserRouter:
| Path | Element | Notes |
|---|---|---|
/ |
MarketingLayout > Home |
The home page ships with the first load |
* |
MarketingLayout > NotFound |
Lazy |
/docs, /docs/* |
DocsLayout > DocPage |
Both lazy; DocPage reads the slug from the path. /docs itself needs the index child, because React Router 7 does not match an empty remainder to the * child |
Fallback: build/notFoundPage.ts copies the built index.html to dist/404.html. Cloudflare Pages then answers any path that is not a file with that page and a real 404 status, instead of treating the site as a single-page application, and the router draws NotFound. Because of that, public/_redirects rewrites /docs and /docs/* to / with status 200, so every docs page still loads with a 200. The target must be /, not /index.html: Pages answers /index.html with its own 308 to /, so a rewrite to it never applies (#138). Check a change to these lines with npx wrangler pages dev dist from site/ after a build. A new top-level marketing page needs the same rewrite line, or it would load with a 404 status. A docs path with no content file shows a docs 404 inside the docs frame (with a 200 status, since the rewrite cannot know which slugs exist).
Links to the app use the constants in src/lib/links.ts: SIGN_IN_URL (https://app.twiligent.ujjwal.fyi/login) and SIGN_UP_URL (the same with ?mode=signup, which shows the app's sign-up headline and Sign up with Google; an emailed code creates the account). Sign-up and sign-in only exist in the app.
A visitor already signed in to the app skips the home page. The app's session lives in its own origin's storage, so the app also sets the cookie twiligent_signed_in=1 on twiligent.ujjwal.fyi while a session exists and clears it when the session ends (frontend/src/lib/signedInCookie.ts; it holds no token). The first script in index.html sends / to https://app.twiligent.ujjwal.fyi/ with location.replace() before the page paints when the cookie is there. Docs and every other path stay readable, and a stale cookie is cleared by the app the moment it finds no session (ADR-042).
Docs Pipeline
Pages. Each page is content/docs/<slug>.mdx; index.mdx is the folder's own page (content/docs/index.mdx is /docs, content/docs/self-host/index.mdx is /docs/self-host). Every file starts with one line:
export const meta = { title: 'Upstash Redis (optional)', description: 'Cache analytics and share rate limits across Worker instances.' }
The title and description become the page heading, the lead paragraph, the document title and the meta tags. The build plugin reads them with a regular expression, so keep the object on one line with single-quoted strings.
Components. MDX files do not import anything. DocPage wraps the page in MDXProvider with MDX_COMPONENTS, which styles the Markdown elements (headings with anchor links, paragraphs, lists, tables, code) and makes Callout, Steps, Step, Cards, Card and Badge available as tags. A link that starts with / is a router link, a # link stays on the page, and any other link opens in a new tab. Code blocks get a copy button.
Navigation. src/docs/nav.ts lists the tabs, the sidebar groups in each tab, and each page's slug, sidebar title and icon. The sidebar, the tabs, the group label above the page title and the previous and next links all come from it.
Loading. DocPage finds pages with import.meta.glob('/content/docs/**/*.mdx'), so each page is its own chunk, loaded when it is opened.
Code highlighting. @shikijs/rehype highlights code blocks at build time with the github-light and github-dark themes. With defaultColor: false, both themes are written as CSS variables, and index.css picks one by data-theme, so code switches with the rest of the page and no highlighter ships to the browser.
Search. build/docsPlugin.ts splits every page into one entry for the text above the first heading and one per ## and ### heading, strips MDX syntax, and indexes the entries with MiniSearch (fields title, page and text; titles weigh most; prefix and fuzzy matching). The serialised index is served as the virtual module virtual:docs-search. Search.tsx imports it the first time someone searches, so it adds nothing to the first load, and each result links to the page with the heading's anchor. Anchors come from slugify() in searchShared.ts, which both the plugin and the Heading component use, so they always agree. In development, editing a page invalidates the module.
Sitemap and llms.txt. After the bundle is written, the plugin writes dist/sitemap.xml (the marketing routes in MARKETING_ROUTES plus every docs page) and dist/llms.txt (a summary and a link with description to every docs page, following llmstxt.org). Both use SITE_URL from the plugin.
Theming
The site has a light (paper) and a dark (dusk) theme, set by data-theme on <html>:
- The inline script in
index.htmlruns before paint: it uses the choice saved inlocalStorageundertwiligent-theme, else the system setting, and falls back to dark when storage is not available. ThemeToggle(in the navbar and the docs top bar) callsuseTheme()fromsrc/lib/theme.ts, which flips the attribute and saves the choice.- Tailwind's
dark:variant is redefined to follow[data-theme="dark"], not the media query.
src/index.css holds the brand palette under its brand names (twiligent-red, ember, oxblood, dusk, paper, afterglow), the semantic tokens for each theme (surface, surface-raised, surface-sunken, line, ink, ink-muted, accent, accent-text and the rest), the type styles (display, eyebrow), the radii, the easing curves and the fold entrance animation. The values come from the brand kit's frontend/public/tokens.json; docs/brand-notes.md records which tokens, type sizes, logo rules, icon rules and voice the site takes from the kit. Components use the semantic tokens (bg-surface, text-ink-muted), never hex values; the platforms' own colours are only for their marks.
The site keeps its own copy of the tokens rather than importing the app's index.css, so a token change in the brand kit must be made in both places.
Icons
The site uses the Solar icon set (480 Design, CC BY 4.0, credited in THIRD_PARTY_NOTICES.md), chosen by the owner on 2026-10-15 to match Activepieces: the bold style for things and places, the linear style for small controls. The app keeps Lucide.
src/components/icons.tsx is generated and is not edited by hand. To add an icon:
- Add a line to the
ICONSlist insite/build/genIcons.ts: the component name and the Solar icon name (for exampleCalendar: 'calendar-bold'). - Run
npm run icons --workspace site. - Import it from
@/components/icons.
Each icon draws in currentColor at 1em, so it takes its colour and size from the text beside it.
Accessibility
The site targets WCAG 2.2 AA. The rules a change must keep:
- Landmarks and skip links: each layout has a skip link (
#main,#doc-content), oneh1per page, and named navigation landmarks. Doc headings nest: a<Steps>block that follows a##heading takeslevel={3}, so its step titles render ash3. - Route changes:
ScrollManagerscrolls to the top and, after the first page, focuses the new page'sh1(giventabindex="-1") so a screen reader announces where the reader landed. A link with a hash scrolls to its section instead. - Focus: the global ring is the accent red; inside the fold and dusk bands (
FoldBand, the footer band, both carryon-band) it is white, because red on red is invisible.htmlhasscroll-padding-top(6rem, 7.5rem under the docs header) so a focused element is never hidden behind the fixed navbar. - Menus: every navbar menu remembers the button that opened it and returns focus there on Escape or an outside click when focus was inside. The phone docs menu is a native modal
<dialog>(showModal()), so focus moves in, stays in, Escape closes it and focus returns to the menu button. - Search: the combobox owns an always-rendered listbox with ids from
useId()(two search boxes exist), options are not focusable, and a polite status line reads the result count. The first Escape closes the results, the second clears the query. - Live messages: the code copy button reports Copied, or the failure with what to do, in a status line.
- Scroll boxes: wide code blocks and docs tables scroll inside a focusable
role="region"with a label, so the keyboard can scroll them. - New tabs: every link that opens a new tab carries a visually hidden "(opens in a new tab)"; the brand bans diagonal arrows, so there is no visible icon.
- Below
xl: the docs outline shows as a closed "On this page" disclosure under the page description. - Example figures: numbers in the platform cards are labelled as examples. Platform logos are not icons: they are hand-written SVG in
src/components/marks.tsx.
Adding a Docs Page
- Create
site/content/docs/<section>/<name>.mdx, starting with theexport const meta = { title: '...', description: '...' }line. - Add
{ slug: '<section>/<name>', title: '...', icon: ... }to the right group insite/src/docs/nav.ts. The order innav.tssets the sidebar order and the previous and next links. - Link to other pages with
/docs/...paths; the content test checks that each one exists. - Run
npm test --workspace siteandnpm run dev:siteto check the page, its outline and its search results.
When a page moves or is renamed, update links to it in other pages and in the app (docsUrl() calls in frontend/src), and add a 301 line for the old path to site/public/_redirects. Pages follow docs/WRITING_STANDARDS.md: no em or en dashes, which the content test enforces.
Adding a Marketing Section or Page
- A home page section is a component in
src/components/sections/, built from the shared blocks inblocks.tsx(SectionHeader,FeatureSection,BentoCard,CtaBand), and placed insrc/pages/HomeBelow.tsx. Product previews are React mockups insrc/components/mockups/, not screenshots. - A new page is a component in
src/pages/, a lazy child of theMarketingLayoutroute insrc/router.tsx, withusePageMeta()for its title and description. Add its path toMARKETING_ROUTESinbuild/docsPlugin.tsso it is in the sitemap, and tonavLinks.tsor the footer if it should be linked. - Motion follows
docs/brand-notes.md: the fold entrance along the 60 degree diagonal, colour-only hover, and a plain fade when the visitor prefers reduced motion (usePrefersReducedMotion).
Mockups and Motion
The product previews are React components drawn with the site's tokens, never screenshots, and every number in them comes from mockups/sample.ts (one made-up creator, Northwind Kitchen) so the pictures agree with each other. Each preview is one role="img" with an aria-label that describes what it shows.
- Loops:
useAutoplay(ref, durations)steps a preview through numbered phases while at least 35% of it is on screen, then loops. It returnsphase,loop(finished loops, used as akeyto restart typing, counting and charts) andreduce. Under reduced motion, or after the reader presses Pause animations, the preview shows its last phase and stays there. - Cursor:
Cursorglides between elements markeddata-cursor="<name>"inside its stage (the element passed asstage, which must also be the cursor's positioned parent), and clicks when itsclickscount goes up. Timings follow the Activepieces previews: a 0.72s glide oncubic-bezier(.5,.02,.2,1), a 0.26s fade, a press to 0.82 scale and a ring that grows from 0.35 to 1.9 while fading over 0.48s. In a bento card, pass it as theFrame'soverlay. - Charts:
AreaChartmeasures its box and draws at real pixels (no stretched SVG), with a monotone curve fromlib/chart.tsthat never overshoots its data, a gradient fill, a dot on the latest point, optionalfocuswith a guide line and tooltip, andanchors(data-cursor="point-<n>") for a cursor to move along the line. It animates in CSS only (chart-play,chart-line,chart-fill,chart-dotinindex.css), so the hero uses it without loading motion. - Text and numbers:
Typedtypes text with a blinking caret;CountUpcounts a number up in fixed-width digits. Numbers never fade in blurred. - Hero:
OverviewWindowuses CSS animations only (rise-in,grow-x, the chart classes) with--delayfor the stagger, because the hero is in the first bundle and motion is not. - Bento cards:
bento/Frameis a small app window that fills its panel and is cut off by the panel's lower edge. Its body is laid out on its own, so a long list never makes the grid row taller. Each card has one live detail (a row arriving, a log streaming, a run completing, a filter clicked). - Reduced motion:
HomeBelowwraps the page inMotionConfig reducedMotion="user";useAutoplayholds the last phase; the CSS animations switch off underprefers-reduced-motion; cursors stay hidden. - Pause control: the previews loop for as long as they are on screen, so WCAG 2.2.2 needs a way to stop them on the page itself.
MotionToggle(in the navbar fromsm, and in the phone menu as Animations) flipsdata-motion="paused"on<html>and saves it inlocalStorageundertwiligent-motion;main.tsxapplies the saved choice before the first render.useStillMotion()is true under reduced motion or the pause, anduseAutoplay,TypedandCountUpuse it;HomeBelowswitchesMotionConfigtoalways; the CSS loops (.ping-soft,.caret) stop under:root[data-motion='paused']. - Story: the pinned scroll story (
MovingStory, 250vh) needs a window at least 1024 px wide and 701 px tall (useMediaQuery); smaller windows, landscape phones and zoomed pages getStillStory, so the closing words are never clipped.
Deploy
| Pages project | twiligent-site |
| Address | https://twiligent.ujjwal.fyi |
| Build | npm run build --workspace site (after npm ci at the root) |
| Output | site/dist (the Vite build plus 404.html, sitemap.xml and llms.txt) |
| Secrets | None in the build; the workflow needs only CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID |
| Workflow | .github/workflows/deploy-site.yml, on pushes to main that touch site/**, tsconfig.base.json, the root package.json or package-lock.json, or the workflow itself |
site/public/_redirects sends the app's old paths on this domain (/login, /accounts, /settings, /videos, /shorts, /tracked-content, /channel/*, /instagram/* and others) to the same path on https://app.twiligent.ujjwal.fyi with a 301; /upload and /publish go to the app's /publish, and /reels and /instagram to its /instagram. The old pages of the platform removed in v2.0.0 (ADR-049) go to the app's Overview, and its old tracked posts path to Tracked content. It also rewrites /docs and /docs/* to / with a 200 (see Routing). In the other direction, the app's /docs/* route sends old docs links to the same page here. site/public/_headers stops other sites from framing the pages and sets the other response headers listed in PAGES.md (Response Headers). See docs/architecture/cloudflare/PAGES.md, docs/architecture/cloudflare/CI_CD.md and docs/workflows/DEPLOYMENT.md.
TypeScript and Lint
| Config | Checks |
|---|---|
site/tsconfig.json |
site/src: DOM lib, jsx: react-jsx, vite/client and mdx types, @/* path |
site/tsconfig.node.json |
vite.config.ts, build/, tests/: Node types |
npm run typecheck --workspace site runs both. MDX files are not type-checked. In eslint.config.mjs, site/** gets the React hooks and React Refresh rules with browser globals, and vite.config.ts, build/** and tests/** get Node globals.
Tests
npm test --workspace site runs node --test "tests/**/*.test.ts":
| Test | Checks |
|---|---|
tests/docs/content.test.ts |
Every page in nav.ts has a content file and every content file is in nav.ts; slugs are unique; every page starts with a meta export with a title and description; every /docs/... link points at a page that exists; no page uses an em or en dash |
tests/docs/searchShared.test.ts |
slugify() turns headings into anchor ids; resultCountText() reads the result count for none, one and many |
tests/lib/motionPreference.test.ts |
Only the stored word paused pauses the previews |
tests/lib/chart.test.ts |
The value range is padded; points spread across the box; the smooth path passes through every point and never overshoots between two; the area closes to the baseline |
tests/lib/format.test.ts |
Full numbers get separators, short numbers use K and M and drop a zero decimal, rates keep one decimal |
tests/homeRedirect.test.ts |
Runs the signed-in script from index.html: the home page opens the app only with twiligent_signed_in=1, and docs and other paths never redirect |
content.test.ts reads nav.ts as text, because nav.ts imports the generated JSX icons, which Node cannot load. The root npm test, npm run typecheck and npm run build include the site, so ci.yml checks it on every pull request.
Local Development
npm run dev:site
This starts Vite for the site alone. It does not need the Worker or any environment file. npm run preview --workspace site serves a production build from site/dist.