diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..fc6f6b355
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,35 @@
+name: CI
+on:
+ push:
+ branches: [master]
+ pull_request:
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '24'
+ cache: npm
+ - run: npm ci
+ - run: npm run lint
+ - run: npm test
+ - run: npm run build
+ e2e:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '24'
+ cache: npm
+ - run: npm ci
+ - run: npx playwright install --with-deps chromium
+ - run: npm run e2e
+ - uses: actions/upload-artifact@v4
+ if: failure()
+ with:
+ name: playwright-report
+ path: playwright-report/
+ retention-days: 7
diff --git a/.gitignore b/.gitignore
index f4f46a5fe..b6ab27677 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,9 @@
# dependencies
/node_modules
+*.tsbuildinfo
+/playwright-report
+/test-results
# profiling files
chrome-profiler-events.json
diff --git a/.travis.yml b/.travis.yml
index ff155b5fa..bd1c1bfc3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,6 +1,6 @@
language: node_js
node_js:
- - "6.9"
+ - "24"
branches:
only:
@@ -8,7 +8,9 @@ branches:
before_script:
- npm install -g firebase-tools
- - npm install -g @angular/cli
+
+install:
+ - npm ci
script:
- npm run build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 840cf8244..7d039bf9b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,27 +1,40 @@
# Contributing
-Thank you for your interest in contributing! Please feel free to put up a PR for any issue or feature request.
-Even if you have little to no experience with Angular, I'll be more than happy to help. :)
+Thank you for your interest! Issues and pull requests are welcome.
## Setup
-1. Fork the repo
-2. Clone your fork
-3. Make a branch for your feature or bug fix
-4. If you don't have Angular CLI installed: `npm install -g angular-cli@latest`
-5. `ng init`
-6. Type `n` for each file to not overwrite any file changes
-7. Run `npm start` and open `localhost:4200` in a browser
-8. Work your magic
-9. Run `npm run build` or `npm run static-serve` to kick off a production build and make sure nothing is broken
-10. To test service worker changes:
- * `npm run build` to kick off a fresh build and update the `dist/` directory
- * `npm run precache` to generate the service worker file
- * `npm run static-serve` to load the application along with the service worker asset using [live-server](https://github.com/tapio/live-server)
-11. Add yourself to the [contributor's list](https://github.com/hdjirdeh/angular2-hn#contributors) in the README!
-12. Commit your changes and reference the issue you're addressing (for example: `git commit -am 'Commit message. Closes #5'`)
-13. Push your branch to your fork
-14. Create a pull request from your branch on your fork to `master` on this repo
-15. Have your branch get merged in! :star2:
-
-If you experience a problem at any point, please don't hesitate to file an issue or send me a message!
+1. Fork and clone the repository, then create a branch for your change.
+2. Use Node.js 24 or newer and run `npm ci` from the repository root.
+3. Run `npm run dev` and open the URL printed by Vite.
+4. Make a focused change and add appropriate regression tests.
+
+## Validation
+
+```sh
+npm run lint
+npm test
+npm run build
+npx playwright install chromium
+npm run e2e
+```
+
+On Linux CI, use `npx playwright install --with-deps chromium` to install browser OS
+dependencies as well. Playwright builds and serves production on port 4173; stop any
+other server on that port first. Tests use deterministic HN API fixtures and cover
+desktop and mobile Chromium, including offline app-shell navigation.
+
+For manual PWA checks, run `npm run build` followed by `npm run preview`. The dev server
+does not enable the service worker. Wait until the worker controls the page before
+testing offline reloads and deep links. API data is deliberately not cached.
+
+## Pull requests
+
+- Keep changes scoped and use shared models, API helpers, and settings contracts.
+- Do not commit `dist/`, dependencies, Playwright reports, or credentials.
+- Commit your changes, push your branch, and open a pull request targeting `master`.
+- Describe the behavior change, test results, and any unverified scenarios. Include
+ desktop/mobile evidence for UI changes.
+
+See the [README](README.md) for architecture, scripts, and deployment information and
+the [license](LICENSE.md) for licensing terms.
diff --git a/README.md b/README.md
index 67cef9e61..2e2059b79 100644
--- a/README.md
+++ b/README.md
@@ -1,102 +1,121 @@
-
-
----
-
-:zap: **Fast:** Service Worker App Shell + Dynamic Content model to achieve faster load times with and without a network.
-
-:iphone: **Responsive:** Completely responsive UI that can be installed to your mobile home screen to provide a native feel.
-
-:rocket: **Progressive:** [Lighthouse](https://github.com/GoogleChrome/lighthouse) score of 87/100.
-
-
-
-
-
-## Mobile Preview
-
-
-
-
-
-## Laptop Preview
-
-
-
-
-
-## Offline Support
-
-This app uses [Workbox](https://workboxjs.org/) to generate a service worker as part of the build step to load quickly and work offline.
-
-## Manifest
-
-With Chromium based browsers for Android (Chrome, Opera, etc...), Angular 2 HN includes a Web App Manifest that allows you to install to your homescreen.
-
-
-
-
-
-## Themes
-
-Built in theme engine!
-
-Current themes:
-* Default
-* Night
-* Black (AMOLED)
-
-More to come!
-
-## Areas of improvement
-
- - Realtime updating using the Firebase SDK (may need to add option to settings so service worker can still rely on REST endpoints)
- - Server side rendering
-
-Feel free to send me feedback on [twitter](https://twitter.com/hdjirdeh) or [file an issue](https://github.com/hdjirdeh/angular2-hn/issues/new)! Feature requests are always welcome.
-
-## Build process
-
-Note: This project has been ejected (with AOT + production settings) in order to customize Webpack configurations.
-
- - Clone or download the repo
- - `npm install`
- - `npm start` to run the application with webpack-dev-server or `npm build` to kick off a fresh build and update the output directory (`dist/`)
-
-Note: Any Service Worker changes will not be reflected when you run the application locally in development. To test service worker changes:
- - `npm build`
- - `npm run precache` to generate the service worker file
- - `npm run static-serve` to load the application along with the service worker asset using [live-server](https://github.com/tapio/live-server)
-
-## Contributors
-
-A million thanks to some awesome people :)
-
-* [Ashwin Sureshkumar](https://github.com/ashwin-sureshkumar)
-* [Mateusz](https://github.com/mateuszwitkowski)
-* [Jordi Collell](https://github.com/jordic)
-* [Ben Brooks](https://github.com/bbrks)
-* [Zach Berger](https://github.com/zachberger)
-* [blAck PR](https://github.com/blackpr)
-* [Bram Borggreve](https://github.com/beeman)
-* [Antonio Indrianjafy](https://github.com/Antogin)
-* [Addy Osmani](https://github.com/addyosmani)
-* [Majid Hajian](https://github.com/mhadaily)
-* [Jeff Cross](https://github.com/jeffbcross)
-* [Minko Gechev](https://github.com/mgechev)
+# Hacker News PWA
+
+A responsive Hacker News client with paginated feeds, nested comments, user profiles,
+and persistent display settings. Built with **React 18**, **TypeScript**, **React Router**,
+and **Vite**. **Workbox**, through `vite-plugin-pwa`, generates the production service
+worker. Profile HTML is sanitized with DOMPurify.
+
+## Getting started
+
+Use **Node.js 24 or newer** and npm. Run commands from the repository root:
+
+```sh
+npm ci
+npm run dev
+```
+
+Open the URL printed by Vite. No Angular CLI or global build tools are required.
+
+| Command | Purpose |
+| --- | --- |
+| `npm run dev` | Start the development server with hot reload. |
+| `npm run build` | Typecheck and build the production app and service worker into `dist/`. |
+| `npm run preview` | Serve the existing production build locally. |
+| `npm run lint` | Run ESLint. |
+| `npm test` | Run Vitest and React Testing Library tests in jsdom. |
+| `npm run e2e` | Build and serve production, then run Playwright in desktop and mobile Chromium. |
+
+Install bundled Chromium before running e2e tests:
+
+```sh
+npx playwright install chromium
+npm run e2e
+# Repeat every test three times:
+npx playwright test --repeat-each=3
+```
+
+Playwright uses port 4173 and manages its own production preview server. API responses
+are mocked from `e2e/fixtures/` so tests do not depend on the live HN API. The HTML report
+is written to `playwright-report/`; failed runs retain traces and screenshots.
+
+## PWA and offline behavior
+
+The production build generates `sw.js` and registers it automatically. Workbox precaches
+the app shell (HTML, JavaScript, CSS), favicon, `manifest.json`, and public icons/images.
+After an online visit finishes installing the service worker and it controls the page,
+reloads and deep links such as `/news/2`, `/item/123`, and `/user/alice` can load the
+app shell offline through the `/index.html` navigation fallback.
+
+**HN API data is not cached**, matching the original Angular app's service-worker
+configuration. Offline pages display a load error while the header/navigation remains
+available; previously viewed stories and profiles are not an offline data store.
+The service worker uses automatic updates. The existing web app manifest and icons
+support installation in compatible browsers.
+
+Service workers are not enabled by the development server. To check the actual PWA:
+
+```sh
+npm run build
+npm run preview -- --port 4173
+```
+
+Use localhost (or HTTPS when deployed), wait for service-worker activation/control,
+then test offline reload/navigation. The Playwright suite covers this against the real
+generated worker, removing API mocks before taking the browser offline.
+
+## Settings
+
+The cog opens controls for Default, Night, and Black (AMOLED) themes, title font size,
+list spacing, and opening external links in a new tab. Settings retain the original
+localStorage keys, including the legacy `amoledblack` theme value. System color-scheme
+changes continue to override and persist the selected theme, as in the original app.
+
+## Project layout
+
+```text
+src/
+ main.tsx Router and settings-provider composition
+ routes.tsx Feed, item, and user routes
+ App.tsx Shared header/footer layout
+ api/ node-hnapi requests, cancellation, and poll aggregation
+ models/ Shared story, comment, user, feed, and settings contracts
+ pages/ Feed/paging, item/comments, and user-profile views
+ components/ Header, footer, settings, loader, and error display
+ settings/ SettingsProvider and useSettings
+ styles/ Shared SCSS themes and layout
+ utils/ Comment-count formatting
+public/ Original manifest, favicon, icons, and images
+e2e/ Production-browser specs and deterministic JSON fixtures
+vite.config.ts React, Vitest, and Workbox/PWA configuration
+playwright.config.ts Desktop/mobile Chromium and production web server
+firebase.json Hosting rewrites, cache headers, and database rules reference
+```
+
+Unit/component tests live beside source files. Shared API requests accept AbortSignals
+and reject HTTP failures. The original API model spelling `User.crated_time` is retained.
+
+## Deployment and CI
+
+Firebase Hosting serves **`dist/`** with an SPA rewrite to `/index.html`. `sw.js` and
+`index.html` have `Cache-Control: no-cache` headers so browsers can revalidate updates.
+`database.rules.json` and the Firebase project aliases in `.firebaserc` are preserved.
+
+`.travis.yml` installs dependencies and builds with Node 24 on `master`, then uses its
+existing Firebase CLI deploy step with `FIREBASE_TOKEN`. Deployment credentials belong
+in CI secrets, not source control.
+
+GitHub Actions (`.github/workflows/ci.yml`) runs on pull requests and pushes to `master`:
+
+- Node 24: `npm ci`, lint, unit tests, and production build.
+- Separate e2e job: install Chromium with OS dependencies, then `npm run e2e`.
+- Upload the Playwright HTML report on failure.
+
+## History, contributing, and license
+
+Originally **Angular 2 HN**, the Angular PWA by
+[Houssein Djirdeh](https://github.com/hdjirdeh), this project has been migrated to React
+while preserving its routes, themes, public assets, and app-shell offline behavior.
+Thanks to the original contributors and maintainers.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull-request guidance and
+[LICENSE.md](LICENSE.md) for the license.
diff --git a/angular.json b/angular.json
deleted file mode 100644
index bae858c47..000000000
--- a/angular.json
+++ /dev/null
@@ -1,134 +0,0 @@
-{
- "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
- "version": 1,
- "newProjectRoot": "projects",
- "projects": {
- "angular-hnpwa": {
- "projectType": "application",
- "schematics": {
- "@schematics/angular:component": {
- "style": "scss"
- }
- },
- "root": "",
- "sourceRoot": "src",
- "prefix": "app",
- "architect": {
- "build": {
- "builder": "@angular-devkit/build-angular:browser",
- "options": {
- "aot": true,
- "outputPath": "dist/angular-hnpwa",
- "index": "src/index.html",
- "main": "src/main.ts",
- "polyfills": "src/polyfills.ts",
- "tsConfig": "tsconfig.app.json",
- "assets": [
- "src/favicon.ico",
- "src/assets",
- "src/manifest.json",
- "src/manifest.webmanifest"
- ],
- "styles": [
- "src/styles.scss"
- ],
- "scripts": []
- },
- "configurations": {
- "production": {
- "fileReplacements": [
- {
- "replace": "src/environments/environment.ts",
- "with": "src/environments/environment.prod.ts"
- }
- ],
- "optimization": true,
- "outputHashing": "all",
- "sourceMap": true,
- "extractCss": true,
- "namedChunks": true,
- "aot": true,
- "extractLicenses": true,
- "vendorChunk": false,
- "buildOptimizer": true,
- "budgets": [
- {
- "type": "initial",
- "maximumWarning": "2mb",
- "maximumError": "5mb"
- },
- {
- "type": "anyComponentStyle",
- "maximumWarning": "6kb"
- }
- ],
- "serviceWorker": true,
- "ngswConfigPath": "ngsw-config.json"
- }
- }
- },
- "serve": {
- "builder": "@angular-devkit/build-angular:dev-server",
- "options": {
- "browserTarget": "angular-hnpwa:build"
- },
- "configurations": {
- "production": {
- "browserTarget": "angular-hnpwa:build:production"
- }
- }
- },
- "extract-i18n": {
- "builder": "@angular-devkit/build-angular:extract-i18n",
- "options": {
- "browserTarget": "angular-hnpwa:build"
- }
- },
- "test": {
- "builder": "@angular-devkit/build-angular:karma",
- "options": {
- "main": "src/test.ts",
- "polyfills": "src/polyfills.ts",
- "tsConfig": "tsconfig.spec.json",
- "karmaConfig": "karma.conf.js",
- "assets": [
- "src/favicon.ico",
- "src/assets",
- "src/manifest.webmanifest"
- ],
- "styles": [
- "src/styles.scss"
- ],
- "scripts": []
- }
- },
- "lint": {
- "builder": "@angular-devkit/build-angular:tslint",
- "options": {
- "tsConfig": [
- "tsconfig.app.json",
- "tsconfig.spec.json",
- "e2e/tsconfig.json"
- ],
- "exclude": [
- "**/node_modules/**"
- ]
- }
- },
- "e2e": {
- "builder": "@angular-devkit/build-angular:protractor",
- "options": {
- "protractorConfig": "e2e/protractor.conf.js",
- "devServerTarget": "angular-hnpwa:serve"
- },
- "configurations": {
- "production": {
- "devServerTarget": "angular-hnpwa:serve:production"
- }
- }
- }
- }
- }
- },
- "defaultProject": "angular-hnpwa"
-}
diff --git a/browserslist b/browserslist
deleted file mode 100644
index 80848532e..000000000
--- a/browserslist
+++ /dev/null
@@ -1,12 +0,0 @@
-# This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
-# For additional information regarding the format and rule options, please see:
-# https://github.com/browserslist/browserslist#queries
-
-# You can see what browsers were selected by your queries by running:
-# npx browserslist
-
-> 0.5%
-last 2 versions
-Firefox ESR
-not dead
-not IE 9-11 # For IE 9-11 support, remove 'not'.
\ No newline at end of file
diff --git a/e2e/app.spec.ts b/e2e/app.spec.ts
new file mode 100644
index 000000000..30a95e31d
--- /dev/null
+++ b/e2e/app.spec.ts
@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { test, expect, type Page } from '@playwright/test';
+
+const item = JSON.parse(readFileSync(new URL('./fixtures/item.json', import.meta.url), 'utf8'));
+const pageTwo = JSON.parse(readFileSync(new URL('./fixtures/page-two.json', import.meta.url), 'utf8')) as Record[];
+const user = JSON.parse(readFileSync(new URL('./fixtures/user.json', import.meta.url), 'utf8'));
+const api = 'https://node-hnapi.herokuapp.com/**';
+
+test.beforeEach(async ({ context }) => {
+ await context.route('https://www.google-analytics.com/**', route => route.abort());
+ await context.route(api, async route => {
+ const url = new URL(route.request().url());
+ if (url.pathname === '/user/alice') return route.fulfill({ json: user });
+ if (url.pathname === '/item/123') return route.fulfill({ json: item });
+ if (url.pathname === '/news') {
+ const stories = url.searchParams.get('page') === '2'
+ ? pageTwo.map(story => ({ ...item, ...story }))
+ : Array.from({ length: 30 }, (_, index) => ({ ...item, id: 123 + index, title: index ? `Top story ${index + 1}` : item.title }));
+ return route.fulfill({ json: stories });
+ }
+ return route.abort();
+ });
+});
+
+async function expectShell(page: Page) {
+ await expect(page.getByRole('banner')).toBeAttached();
+ await expect(page.getByRole('banner').getByRole('img', { name: 'Logo', exact: true })).toBeVisible();
+ await expect(page.getByRole('link', { name: 'new', exact: true })).toBeVisible();
+ await expect(page.getByRole('button', { name: 'Settings', exact: true })).toBeVisible();
+}
+
+test('loading shell shows before React mounts and hides afterwards', async ({ page, context }, testInfo) => {
+ let release!: () => void;
+ const ready = new Promise(resolve => { release = resolve; });
+ await context.route('**/assets/index-*.js', async route => {
+ await ready;
+ await route.continue();
+ });
+ try {
+ await page.goto('/', { waitUntil: 'commit' });
+ await expect(page.locator('#root')).toBeEmpty();
+ await expect(page.locator('.app-loader')).toHaveCSS('opacity', '1');
+ } finally {
+ release();
+ }
+ await expectShell(page);
+ await expect(page.locator('#root')).not.toBeEmpty();
+ await expect(page.locator('.app-loader')).toHaveCSS('opacity', '0');
+ await testInfo.attach('mounted-shell', { body: await page.screenshot(), contentType: 'image/png' });
+});
+
+test('feed loads, pages forward and returns with Prev', async ({ page }) => {
+ await page.goto('/');
+ await expect(page).toHaveURL(/\/news\/1$/);
+ await expect(page.getByRole('link', { name: item.title, exact: true })).toBeVisible();
+ await page.getByRole('link', { name: 'More' }).click();
+ await expect(page).toHaveURL(/\/news\/2$/);
+ await expect(page.getByRole('link', { name: 'Second page story', exact: true })).toBeVisible();
+ await expect(page.getByRole('link', { name: item.title, exact: true })).toHaveCount(0);
+ await page.getByRole('link', { name: 'Prev' }).click();
+ await expect(page).toHaveURL(/\/news\/1$/);
+ await expect(page.getByRole('link', { name: item.title, exact: true })).toBeVisible();
+});
+
+test('comments link opens item and nested comments can collapse', async ({ page }) => {
+ await page.goto('/');
+ await page.getByRole('listitem').filter({ has: page.getByRole('link', { name: item.title, exact: true }) })
+ .getByRole('link', { name: '2 comments' }).filter({ visible: true }).click();
+ await expect(page).toHaveURL(/\/item\/123$/);
+ await expect(page.getByRole('link', { name: item.title, exact: true }).filter({ visible: true })).toBeVisible();
+ await expect(page.getByText('Parent comment', { exact: true })).toBeVisible();
+ await expect(page.getByText('Nested comment', { exact: true })).toBeVisible();
+ await page.getByRole('button', { name: 'Collapse comment by parent', exact: true }).click();
+ await expect(page.getByText('Nested comment', { exact: true })).toBeHidden();
+ await page.getByRole('button', { name: 'Expand comment by parent', exact: true }).click();
+ await expect(page.getByText('Nested comment', { exact: true })).toBeVisible();
+});
+
+test('profile renders fields and sanitized about markup', async ({ page }) => {
+ await page.goto('/user/alice');
+ await expect(page.getByText('1234 ★', { exact: true })).toBeVisible();
+ await expect(page.getByText('Created 10 years ago', { exact: true })).toBeVisible();
+ await expect(page.locator('b').filter({ hasText: 'About Alice' })).toBeVisible();
+ await expect(page.getByRole('link', { name: 'Website' })).toHaveAttribute('href', 'https://example.com/alice');
+ await expect(page.locator('.other-details script, .other-details [onerror]')).toHaveCount(0);
+ expect(await page.evaluate(() => Reflect.get(window, 'unsafeAbout'))).toBeUndefined();
+});
+
+test('AMOLED theme persists across reload', async ({ page }) => {
+ await page.goto('/');
+ await page.getByRole('button', { name: 'Settings', exact: true }).click();
+ await page.getByRole('radio', { name: 'Black (AMOLED)', exact: true }).check();
+ await expect(page.locator('#root > .amoledblack')).toBeVisible();
+ await page.getByRole('button', { name: 'Close settings' }).click();
+ await page.reload();
+ await expect(page.locator('#root > .amoledblack')).toBeVisible();
+ await page.getByRole('button', { name: 'Settings', exact: true }).click();
+ await expect(page.getByRole('radio', { name: 'Black (AMOLED)', exact: true })).toBeChecked();
+});
+
+test('service worker serves reload and uncached deep link offline without caching API data', async ({ page, context }, testInfo) => {
+ const pageErrors: string[] = [];
+ page.on('pageerror', error => pageErrors.push(error.message));
+ await page.goto('/');
+ await expect(page.getByRole('link', { name: item.title, exact: true })).toBeVisible();
+ await page.evaluate(async () => { await navigator.serviceWorker.ready; });
+ if (!await page.evaluate(() => !!navigator.serviceWorker.controller)) await page.reload();
+ await expect.poll(() => page.evaluate(() => !!navigator.serviceWorker.controller)).toBe(true);
+ await context.unroute(api);
+ await context.setOffline(true);
+ await page.reload();
+ await expectShell(page);
+ await expect(page.getByText('Could not load news stories.', { exact: true })).toBeVisible();
+ await page.goto('/item/123');
+ await expect(page).toHaveURL(/\/item\/123$/);
+ await expectShell(page);
+ await expect(page.getByText('Could not load item comments.', { exact: true })).toBeVisible();
+ expect(pageErrors).toEqual([]);
+ await testInfo.attach('offline-shell', { body: await page.screenshot(), contentType: 'image/png' });
+});
diff --git a/e2e/fixtures/item.json b/e2e/fixtures/item.json
new file mode 100644
index 000000000..88af8a525
--- /dev/null
+++ b/e2e/fixtures/item.json
@@ -0,0 +1,23 @@
+{
+ "id": 123,
+ "title": "Deterministic top story",
+ "points": 42,
+ "user": "alice",
+ "time": 0,
+ "time_ago": "1 hour ago",
+ "type": "story",
+ "url": "https://example.com/story",
+ "domain": "example.com",
+ "comments_count": 2,
+ "content": "