A pnpm workspace of three packages and the data they share.
| Folder | |
|---|---|
shared/ |
Types, scoring, PR type rules, periods, countries, the repositories on the board. Used by both others. |
collector/ |
Collects landed PRs, issues, discussions, comments, review comments, security advisories, the Angular team and GitHub profiles, writes data/. Runs nightly in GitHub Actions. |
app/ |
The site: Analog (Angular 22, server-rendered), spartan/ui, Tailwind 4. |
data/ |
The collector's output: contributors*.json, profiles.json, packages.json, calendar.json, team.json, renames.json, meta.json. Committed. |
Every night .github/workflows/collect.yml collects each repository in a job of its own, in parallel, and a last job merges them
into data/ and commits it; that commit deploys the site. Details: collector/README.md.
Changes land on development and reach main, the live site, in releases; main is merged back into development after
each, so it has the nightly data. Netlify's build minutes are limited: ignore in netlify.toml skips a build when only
docs, Markdown, agent skills or GitHub config changed. Netlify builds no deploy previews: .github/workflows/ci.yml runs the tests, the
types and the build on every pull request and every push to development.
Each profile has an Angular-only contribution graph: calendar.json holds every contributor's contributions of their own
per UTC day (merged PRs on the day they landed, issues, discussions, comments, review comments, security advisory credits, translations; not
reactions received), as day numbers from 1 January 2014 and counts (encodeCalendar in shared/src/calendar.ts). The
profile sends a person their days with their profile; profile/contribution-grid.ts lays out the year picked, or the
days the 12-month stats count (periodDays in shared/src/periods.ts), in weeks, each day shaded against that person's
busiest day; for the last 30 days, the 12 months are drawn and only those 30 days are counted, the rest dimmed, and the current year is
drawn whole, the days still to come dimmed. A list
beside it (Last 30 days, Last 12 months, each year) switches the profile's period. Hovering a day shows its count; the (i) by the title opens a dialog with what counts and the repositories. Visitors can switch
the graph from gold to GitHub's green; the choice is kept in their browser (angularians-graph-colors) and applied
before the first paint by app/index.html, as the theme is (the graph-green class on <html>).
Angular 22 uses OnPush change detection and standalone components by default; omit explicit declarations of those defaults.
Root services use @Service() (available since Angular 22.1), which preserves the application-wide, tree-shakable scope of
@Injectable({ providedIn: 'root' }). Keep manual providers when they configure a dependency or give it a local scope.
Every page is server-rendered on Netlify by one function (Nitro's netlify preset, configured in netlify.toml);
static assets go to the CDN. Pages and API responses are cached by the CDN for a day, in Netlify's durable cache (netlify-cdn-cache-control: one copy shared by every edge), and each deploy clears that cache. Server functions (/_analog/**) are no-store: they are POSTs whose input is in the body, which the CDN's cache key ignores. Any 5xx answer, a failed render included, is no-store (app/src/server/plugins/no-cache-errors.ts).
The CDN keeps one copy per value of the parameters the routes read (netlify-vary in app/vite.config.ts); any other query parameter shares that copy, so a route reading a new one must add it there.
Each page lists its own lazy chunks as modulepreload links, so the browser fetches them with the entry instead of after it: the client build's Vite manifest goes to the server as an asset (app/dist/client-manifest, never published), and app/src/server/plugins/preload-page.ts adds the chunks of the page the path maps to.
Browsers keep /assets/* and /fonts/* for a year and /flags/* for 30 days (netlify.toml).
The data is read once per server instance from a JSON file next to the server (app/scripts/bundle-data.ts writes it from
readDataDir of @angularians/shared/node, which validates every file of data/; app/scripts/copy-data.ts copies it there): at ~25 MB it is too big to compile into the server.
In development, card and OG image requests are forwarded to Nitro handlers. Keep their paths in app/vite.config.ts
relative to app/: Windows absolute paths become invalid ESM imports in Nitro's dev bundle.
Pages load their data with injectSeededServerFn (app/src/app/data/seeded-server-fn.ts), not Analog's
injectServerFn: it hands the browser the server's value on the first render, so hydration keeps the server-rendered page
instead of rebuilding it. Later inputs load as usual.
A page is hydrated when its route resolves, a moment after the rest of the app, and Angular then writes each element's
static class over the server's classes before the spartan/ui directives' first effect sets theirs, with a paint in
between: classes() in app/src/ui/utils/src/lib/hlm.ts puts the server's classes back until then, or the page's buttons
and tabs would lose their size for a frame and move what is around them. Meanwhile it notes Angular's own classes (the
static ones, and what [class.x] bindings add or remove through classList), which the first effect keeps.
To try the site with another data folder: CONTRIBUTORS_DATA_DIR=/path/to/data pnpm build.
The brand font, Norse Bold (the word "Angularian" on the site and the cards), is in app/public/fonts/; it and
Manrope's Latin file are preloaded (app/index.html), so the text does not move when they arrive. The mark is built by app/scripts/logo/build.py.
On a reload or back/forward, an inline script in app/index.html makes the page render-blocking until the footer
(#site-footer) is parsed: the browser restores the scroll position in the first paint instead of drawing the top of
the page first. A first visit is not held back.
A launch post, once out, goes in LAUNCH_POST (app/src/app/site.ts): the home page then shows a dashed callout linking to it under its introduction (leaderboard/launch-post-callout.ts).
The site's colours are variables in app/src/styles.css, each set there once per theme: its light
value in :root, its dark value, when it differs, in :root.dark just below. Components use them as var(--name) in
their .css, or as a utility where @theme inline exposes one (text-brand, bg-angular-pink/10). The only colours
that are not variables are the fixed hex listed below.
| Group | Tokens | Used by |
|---|---|---|
| Spartan's theme | --background, --foreground, --card, --popover, --primary, --secondary, --muted, --accent, --destructive, --border, --input, --ring (and their -foreground), --radius |
the UI components and every page, as Tailwind utilities (bg-muted, rounded-lg) |
| The brand | --primary (Viking gold: on light the mark's --mark-2), --color-brand (utility text-brand), --font-display (Norse) |
the mark, the word Angularians |
| The mark | --mark-empty, --mark-1 to --mark-3 (its graph, the same in both themes), --mark-intro-1 to --mark-intro-3 (the greens of its intro and hover) |
logo-mark |
| Angular | --angular-pink, --angular-purple (utilities *-angular-pink, *-angular-purple) |
the team badge, the Angular guide |
| GitHub | --github-purple, -red, -blue, -gold, -green, -pink, -orange; --github-*-on-light, GitHub's light-theme value in both themes; --github-gold-text, --github-green-text, a shade darker on light for text on a tint |
the kinds of contribution, with the github-* classes of styles/github-colors.css; the profile's stat tints; the gold and green badges |
| Medals | --medal-gold, --medal-silver, --medal-bronze and their -text |
the top three, through the classes of styles/podium.css (which set --podium-ring and --podium-text) |
| Badges | --shieldwall |
the Shieldwall badge, for Angular's security advisories (styles/badge-tones.css) |
| Projects | --idea-library, --idea-tool, --idea-meetup, --idea-teaching |
the kinds of project in "Forged something for Angular?" |
| The globe | --globe-base, --globe-glow (and --primary for its land) |
the world globe's WebGL colours, read by world/globe.ts |
| GitHub's graph | --graph-green-0 to --graph-green-4: GitHub's own contribution greens, another project's colours |
the contribution graph in green, when a visitor picks it |
| The contribution graph | --calendar-0 (an empty day) to --calendar-4 (the busiest): the mark's grey, its three golds and the gold halfway between two of them; on light the lightest gold is the fewest, on dark the darkest |
profile/contribution-calendar.css |
| The storm | --lightning, --lightning-inner, --angie-shadow (the same in both themes) |
Angie's storm, layout/hammer-strike.css |
A token that means another one is written as it (--primary: var(--mark-2), --idea-library: var(--github-pink),
--shieldwall: var(--github-red)). Some share a hex but not a meaning, and stay separate so that one can change
alone: GitHub's gold (--github-gold) and the brand (--primary), the gold medal (--medal-gold, --medal-gold-text)
and both, the tool kind of project (--idea-tool) and the silver medal's text.
Spacing, font sizes, shadows and z-indexes are Tailwind's own scale (--spacing, --text-*, --shadow-*); a one-off
size for one element (text-[5.5rem] for the hero's word) stays an arbitrary value where it is used.
Spartan's preset also maps sidebar and chart colours (--color-sidebar*, --color-chart-*) to variables this theme
does not set; @theme inline in styles.css unmaps them, so bg-sidebar makes no CSS rather than a transparent colour.
Fixed hex stays only where no theme applies, in four cases (AGENTS.md lists the same):
- another project's own colour (a badge's tone in
styles/badge-tones.css, a translation's flag there, the Discord and YouTube guides), set once in a variable on the element when it is used more than once; - the artwork of a logo (
angular-logo.html, YouTube's); - black or white as a shade, a mask or over a photo (the rank shield's darker half, the globe's fade, the leaderboard's names on avatars);
- the server-drawn cards (
app/src/server/cardand their preview in the share dialog), which have no theme.
To add a colour: give it a name for what it is, not how it looks (--medal-gold, not --yellow), put it in its group in
styles.css with its dark value next to it if it changes, add a --color-* line to @theme inline only when a template
needs it as a utility, and remove any token nothing uses any more.
An easter egg, which the account menu turns off for good (layout/angie.service.ts), and which its "My Angularian profile" link also calls; after the first storm a dialog (layout/angie-intro.ts) introduces her once, with the off switch and the star and sponsor links: the word "Angularian(s)" or "ng-halla", or a click on the header's or footer's logo, calls Angie (app/public/angie/) to bring down a storm with thunder (app/public/sounds/), on a click on the word, once a visit on a click on a logo, or once a visit on hover after a first click; app/src/app/layout/hammer-strike.ts, the bolt's shape in lightning.ts.
/sitemap.xml(app/src/server/routes/sitemap.xml.get.ts): the home page, each country's board and the profile of everyone with a merged PR, dated with the last collection.robots.txtpoints to it and keeps crawlers out of/api/.- One address per page:
angularians.netlify.app(at the CDN, a redirect innetlify.toml) and a trailing slash (/erkamyaman/) answer 301 to the canonical URL (app/src/server/middleware/canonical-url.ts); every page sets<link rel="canonical">. A period (?period=) is the same page as the home page without one (the last 12 months); a country (?country=TR) is a page of its own, with its own title. Badges (?badges=,?match=) are a filter of the same page, with the same canonical URL. - Structured data (
setJsonLdinapp/src/app/seo-head.ts):WebSiteon the home page,ProfilePagewith itsPersonand aBreadcrumbListon profiles, aBreadcrumbListon a country's board. - The cards (
/og.png,/:username/card.png) keep their bottom-left corner free: X lays the page's title over it. - Renamed accounts: each run compares usernames with the previous run's by GitHub id and keeps the old ones in
data/renames.json./oldnameand/oldname/card.pnganswer 301 to the new name (app/src/server/middleware/renamed-user.ts), so a README card keeps working; a name someone contributes under now stays theirs.
Through the user authorization of the angularians-collector GitHub App. Only the GitHub id and login are kept, in a sealed,
http-only cookie; GitHub's access token is used once, to ask who signed in. The session is read in the browser
(/api/auth/me), never in a cached page. A readable hint cookie, angularians-signed-in (app/src/app/auth/hint.ts),
says the browser was signed in last time; the CDN keeps a copy of each page per value, so the server draws the signed-in
card's skeleton (laid out as an Angularian's card, at its height, and the card is never shorter) and the header's avatar
place, and leaves out the profile's "Is this your profile?" prompt for it, and draws the sign-in and the prompt for
everyone else: nothing jumps when the session answers. A hint whose session has ended gets the sign-in in the skeleton's
place and size, and in the avatar's, once: /api/auth/me clears it. Without the hint the browser does not ask at all: /api/auth/me cannot be cached, and every call counts against Netlify's function limit. A session check that fails counts as signed out,
so the page stays as the server drew it.
Sign-in stays hidden until the site has these environment variables; without them the server draws the page without
the sign-in and the prompt (SIGN_IN_SET_UP, a fact about the site, not the visitor):
| Variable | |
|---|---|
GITHUB_CLIENT_ID |
The GitHub App's client id |
GITHUB_CLIENT_SECRET |
One of its client secrets |
SESSION_SECRET |
32 characters or more, to seal the cookie |
The App's callback URL is https://angularians.dev/api/auth/callback. To sign in locally, add http://localhost:4242/api/auth/callback as well.
The App must be public: GitHub answers 404 to everyone but its owner when it is private.
Signing in from the home page ends on your profile, or back on the home page if you have no contributions. From any other page, it ends on that page.
| Route | |
|---|---|
GET /api/contributors?period=12m&country=TR&badges=angular-gde,github-star&match=all&page=1 |
One page (100) of the leaderboard, with each profile's name when it has one; filtered on a country, also each row's countryRank; filtered on badges, anyone with at least one of them, or with match=all only those with all of them |
GET /api/contributors/:username |
A profile: all-time stats, rank in each period, links |
GET /api/search/contributors?q=cris&country=TR |
Up to 8 contributors, of that country if given |
GET /api/map/contributors?period=all |
Contributors by country, and every badge on the board with how many hold it in the period |
GET /:username/card.png?period=2025&flag=TR&hide=reviewer&names=official&avatar=off&username=off |
The Angularian card, 2400×1260: the README card and the profile's link preview. avatar=off and username=off leave the GitHub avatar and the username off (on a GitHub profile both already sit beside the README), and the profile's own ?avatar=off&username=off carries them to its link preview. names=official swaps fun project titles for the project and role, names=none shows the badges as icons alone; hide is the badges the owner left out in the share dialog (app/src/app/profile/card-badges.ts), and the profile's own ?hide= carries them to its link preview. Its flag is the GitHub location's country, or flag when the owner picked another; under its stats, the profile's badges as tags with their names, as many as fit in up to three rows (the stats shrink for a third) and the rest as icons alone, a language's own name in Manrope's Cyrillic and extended Latin or a small Noto font holding just its letters (TAG_FONTS in app/src/server/card/tag-fonts.ts) (earnedBadges in app/src/app/profile/earned-badges.ts, shared with the profile page; images from the site-images server asset) |
GET /og.png?period=2025 |
The home page's link preview, 2400×1260: all time, or the top of a period |