Migrate to TypeScript & fix Netlify PR previews

.nvmrc

@@ -1 +1 @@
-18
+24

netlify.toml

@@ -0,0 +1,3 @@
+[build]
+  # Production is hosted on GitHub Pages; Netlify provides PR previews only.
+  ignore = 'test "$CONTEXT" = "production"'

package.json

@@ -19,7 +19,8 @@
     "test:start": "SITE_URL=http://127.0.0.1:7987 npm run build && npm run test:serve",
     "test:run": "npm run test:validate && npm run test:e2e",
     "test:validate": "swup validate --parallel --sitemap=_site/sitemap.xml",
-    "test:e2e": "playwright test"
+    "test:e2e": "playwright test",
+    "typecheck": "tsc"
   },
   "dependencies": {
     "@alpinejs/focus": "^3.12.0",
@@ -48,13 +49,14 @@
     "@sindresorhus/slugify": "^1.1.0",
     "@swup/cli": "^5.0.5",
     "@swup/prettier-config": "^1.1.0",
-    "autoprefixer": "^10.4.2",
+    "@types/alpinejs": "^3.17.0",
+    "@types/alpinejs__focus": "^3.13.4",
+    "@types/alpinejs__persist": "^3.17.0",
+    "@types/node": "^24.19.2",
     "browserslist": "^4.21.4",
-    "child_process": "^1.0.2",
     "concurrently": "^8.0.1",
     "copy-webpack-plugin": "^11.0.0",
     "css-loader": "^6.6.0",
-    "debug": "^4.3.4",
     "eleventy-plugin-toc": "^1.1.5",
     "esbuild-loader": "^4.3.0",
     "esbuild-plugin-browserslist": "^0.16.0",
@@ -68,18 +70,16 @@
     "markdown-it-shiki-extra": "^0.1.5",
     "markdown-it-video": "^0.6.3",
     "mini-css-extract-plugin": "^2.5.3",
-    "minimist": "^1.2.5",
     "pagefind": "^1.1.1",
     "postcss": "^8.4.31",
     "postcss-loader": "^6.2.1",
     "postcss-preset-env": "^7.8.3",
     "prettier": "^2.7.1",
-    "sass": "^1.62.0",
-    "sass-loader": "^12.6.0",
+    "sass": "^1.107.1",
+    "sass-loader": "^17.1.0",
     "shiki": "^0.14.1",
     "start-server-and-test": "^2.0.3",
-    "ts-loader": "^9.2.6",
-    "url-loader": "^4.1.1",
+    "typescript": "^7.0.2",
     "webpack": "^5.105.0",
     "webpack-cli": "^4.9.2",
     "webpack-livereload-plugin": "^3.0.2",

src/_assets/components/alpine/ColorSchemeSwitcher/ColorSchemeSwitcher.js → src/_assets/components/alpine/ColorSchemeSwitcher/ColorSchemeSwitcher.ts

@@ -1,5 +1,7 @@
-export default function () {
-	return {
+import { defineComponent } from '~/utils';
+
+export default () =>
+	defineComponent({
 		// Find this function in `head.njk`
 		scheme: window.getColorSchemePreference(),
 		switchTheme() {
@@ -8,5 +10,4 @@ export default function () {
 			document.documentElement.classList.remove('dark', 'light');
 			document.documentElement.classList.add(this.scheme);
 		}
-	};
-}
+	});

src/_assets/components/alpine/Intro/Intro.js → src/_assets/components/alpine/Intro/Intro.ts

@@ -1,4 +1,5 @@
 import { gsap } from 'gsap';
+import { defineComponent } from '~/utils';
 
 export default () => {
 	const tl = gsap.timeline({ delay: 0.5 });
@@ -29,7 +30,7 @@ export default () => {
 
 	const letterDelay = '<0.1';
 
-	return {
+	return defineComponent({
 		async init() {
 			this.$root.style.visibility = 'hidden';
 
@@ -68,14 +69,14 @@ export default () => {
 		sliceLogo() {
 			const refs = ['s', 'w', 'u', 'p', 'dot1', 'dot2'];
 			const paths = this.$refs.logo.querySelectorAll('path');
-			const parentNode = this.$refs.logo.parentNode;
+			const parentNode = this.$refs.logo.parentNode!;
 			paths.forEach((path, index) => {
-				const clone = this.$refs.logo.cloneNode();
+				const clone = this.$refs.logo.cloneNode() as Element;
 				clone.setAttribute('x-ref', refs[index]);
 				clone.append(path.cloneNode());
 				parentNode.append(clone);
 			});
 			this.$refs.logo.remove();
 		}
-	};
+	});
 };

src/_assets/components/alpine/MobileNav/MobileNav.ts

@@ -0,0 +1,16 @@
+import { defineComponent } from '~/utils';
+
+export default () =>
+	defineComponent({
+		navHTML: '',
+		isOpen: false,
+		init() {
+			this.navHTML = document.querySelector('.nav')?.innerHTML ?? '';
+		},
+		open() {
+			this.isOpen = true;
+		},
+		close() {
+			this.isOpen = false;
+		}
+	});

src/_assets/components/alpine/Page/Page.ts

@@ -0,0 +1,58 @@
+import tippy from 'tippy.js';
+import { defineComponent, isTouch } from '~/utils';
+
+export default () =>
+	defineComponent({
+		init() {
+			this.initHeadlineLinks();
+			this.initCodeBlocks();
+		},
+		initCodeBlocks() {
+			this.$root.querySelectorAll('.code-block').forEach((block) => {
+				const copyButton = block.querySelector<HTMLElement>('.code-block_copy')!;
+				const copyText = block.querySelector('.shiki > code')?.textContent ?? '';
+
+				if (!isTouch()) {
+					tippy(copyButton, {
+						animation: 'none',
+						placement: 'bottom',
+						content: 'Copy'
+					});
+				}
+
+				const copiedTip = tippy(copyButton, {
+					animation: 'none',
+					placement: 'bottom',
+					trigger: 'click',
+					content: 'Copied!',
+					onShow() {
+						setTimeout(copiedTip.hide, 2000);
+					}
+				});
+
+				copyButton.addEventListener('click', () => navigator.clipboard.writeText(copyText));
+			});
+		},
+		initHeadlineLinks() {
+			document
+				.querySelectorAll<HTMLAnchorElement>('.page_body .header-anchor')
+				.forEach((anchor) => {
+					const target = anchor.querySelector('span')!;
+
+					const copiedTip = tippy(target, {
+						placement: 'bottom',
+						trigger: 'click',
+						content: 'URL copied!',
+						offset: [0, 10],
+						triggerTarget: anchor,
+						arrow: true,
+						onShow() {
+							setTimeout(copiedTip.hide, 2000);
+						}
+					});
+					anchor.addEventListener('click', () =>
+						navigator.clipboard.writeText(anchor.href)
+					);
+				});
+		}
+	});

src/_assets/components/alpine/Search/Search.js → src/_assets/components/alpine/Search/Search.ts

@@ -1,8 +1,10 @@
-export default () => {
-	return {
+import { defineComponent } from '~/utils';
+
+export default () =>
+	defineComponent({
 		isOpen: false,
 		metaKey: navigator.platform.indexOf('Mac') === 0 ? '⌘' : 'Ctrl+',
-		onKeyDown(e) {
+		onKeyDown(e: KeyboardEvent) {
 			if (e.key === '/' || (e.key === 'k' && (e.ctrlKey || e.metaKey))) {
 				e.preventDefault();
 				this.open();
@@ -15,5 +17,4 @@ export default () => {
 		close() {
 			this.isOpen = false;
 		}
-	};
-};
+	});

src/_assets/components/alpine/SearchUI/SearchUI.js → src/_assets/components/alpine/SearchUI/SearchUI.ts

@@ -1,10 +1,28 @@
+import Alpine from 'alpinejs';
+import { defineComponent } from '~/utils';
+
+/** The parts of the pagefind JS API we use */
+type Pagefind = {
+	search(term: string): Promise<{ results: { data(): Promise<PagefindResult> }[] }>;
+};
+type PagefindResult = {
+	url: string;
+	excerpt: string;
+	meta: Record<string, string>;
+};
+
+/** Generated by pagefind on build, not bundled */
+const pagefindUrl = '/pagefind/pagefind.js';
+
 export default () => {
 	const postsPerPage = 10;
 
-	return {
+	return defineComponent({
 		term: '',
-		results: [],
+		results: [] as PagefindResult[],
 		isSearching: false,
+		/** Provided by the parent `Search` component */
+		isOpen: false,
 		init() {
 			this.$watch('term', this.search.bind(this));
 			Alpine.effect(async () => {
@@ -18,20 +36,20 @@ export default () => {
 			this.isSearching = false;
 			this.term = '';
 		},
-		async search(term) {
+		async search(term: string) {
 			if (term.trim().length < 2) {
 				this.results = [];
 				this.isSearching = false;
 				return;
 			}
 			this.isSearching = true;
-			const pagefind = await import(/* webpackIgnore: true */ '/pagefind/pagefind.js');
+			const pagefind: Pagefind = await import(/* webpackIgnore: true */ pagefindUrl);
 			const search = await pagefind.search(term);
 			const results = await Promise.all(
 				search.results.slice(0, postsPerPage).map((r) => r.data())
 			);
 			this.results = results;
 			this.isSearching = false;
 		}
-	};
+	});
 };

src/_assets/components/alpine/SwupThemeSwitcher/SwupThemeSwitcher.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from '~/utils';
+
+export default () => defineComponent({});

src/_assets/components/alpine/TableOfContents/TableOfContents.js → src/_assets/components/alpine/TableOfContents/TableOfContents.ts

@@ -1,9 +1,11 @@
+import { defineComponent } from '~/utils';
+
 export default () => {
-	return {
-		wrap: null,
+	return defineComponent({
+		wrap: null as HTMLElement | null,
 		lastChild: null,
 		horizon: 150,
-		sections: [],
+		sections: [] as HTMLElement[],
 		async init() {
 			await this.$nextTick();
 			this.wrap = document.querySelector('.page_body');
@@ -20,7 +22,10 @@ export default () => {
 		},
 		// Store a reference to all sections in reversed order
 		prepareSections() {
-			this.sections = [...this.wrap.querySelectorAll('h2[id],h3[id],h4[id]')].reverse();
+			if (!this.wrap) return;
+			this.sections = [
+				...this.wrap.querySelectorAll<HTMLElement>('h2[id],h3[id],h4[id]')
+			].reverse();
 		},
 		/**
 		 * Marks the current section with the class "is-active"
@@ -56,5 +61,5 @@ export default () => {
 				}) || firstSection
 			);
 		}
-	};
+	});
 };

src/_assets/components/alpine/VersionSelect/VersionSelect.js → src/_assets/components/alpine/VersionSelect/VersionSelect.ts

@@ -1,15 +1,15 @@
 import tippy from 'tippy.js';
+import { defineComponent } from '~/utils';
 
-export default () => {
-	return {
+export default () =>
+	defineComponent({
 		init() {
 			tippy(this.$refs.button, {
-				content: this.$refs.options.content,
+				content: (this.$refs.options as HTMLTemplateElement).content,
 				allowHTML: true,
 				interactive: true,
 				trigger: 'click'
 				// theme: 'light',
 			});
 		}
-	};
-};
+	});