From b4e50eb489e2b3aec4c6162030b7a9e94f53fae4 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 3 Feb 2026 13:29:24 +0000 Subject: [PATCH] docs: create comprehensive README with project documentation Co-Authored-By: Joao Esteves --- README.md | 271 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 223 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 67cef9e6..9a9a932c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ +# Angular Hacker News PWA +

- Angular 2 HN + Angular HN

@@ -9,94 +11,267 @@

- View App + View Live App

PRs Welcome Build Status + Angular + License

--- -:zap: **Fast:** Service Worker App Shell + Dynamic Content model to achieve faster load times with and without a network. +## Overview + +Angular Hacker News PWA is a progressive web application that provides a fast, responsive, and offline-capable interface for browsing Hacker News content. Built with Angular 9, it leverages modern web technologies to deliver a native-like experience on both desktop and mobile devices. + +### Key Features + +**Fast Performance**: Service Worker App Shell combined with a dynamic content model achieves faster load times with and without a network connection. + +**Responsive Design**: A completely responsive UI that adapts seamlessly to any screen size, from mobile phones to large desktop monitors. + +**Progressive Web App**: Achieves a Lighthouse score of 87/100 and can be installed to your mobile home screen for a native app-like experience. -:iphone: **Responsive:** Completely responsive UI that can be installed to your mobile home screen to provide a native feel. +**Offline Support**: Uses service workers to cache content and provide offline functionality, allowing you to browse previously loaded content without an internet connection. -:rocket: **Progressive:** [Lighthouse](https://github.com/GoogleChrome/lighthouse) score of 87/100. +**Theme Support**: Built-in theme engine with multiple themes including Default, Night, and Black (AMOLED-friendly).

- +

-## Mobile Preview +## Demo + +### Mobile Preview

- +

-## Laptop Preview +### Desktop Preview

- +

-## Offline Support +## Technology Stack + +This project is built with the following technologies: + +| Technology | Version | Purpose | +|------------|---------|---------| +| Angular | 9.0.1 | Frontend framework | +| TypeScript | 3.7.5 | Programming language | +| RxJS | 6.5.4 | Reactive programming | +| Angular Service Worker | 9.0.1 | PWA/offline support | +| SCSS | - | Styling | +| Karma/Jasmine | - | Unit testing | +| Protractor | 5.4.0 | E2E testing | +| Firebase | - | Hosting | + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- **Node.js**: Version 12.x or higher +- **npm**: Version 6.x or higher (comes with Node.js) +- **Angular CLI**: Version 9.x (`npm install -g @angular/cli@9`) + +## Installation + +1. Clone the repository: +```bash +git clone https://github.com/COG-GTM/angular2-hn.git +cd angular2-hn +``` + +2. Install dependencies: +```bash +npm install +``` + +3. Start the development server: +```bash +npm start +``` + +4. Open your browser and navigate to `http://localhost:4200` + +## Available Scripts + +| Command | Description | +|---------|-------------| +| `npm start` | Start the development server at `localhost:4200` | +| `npm run build` | Build the application for production | +| `npm test` | Run unit tests with Karma | +| `npm run lint` | Run TSLint for code quality checks | +| `npm run e2e` | Run end-to-end tests with Protractor | + +## Project Structure + +``` +angular2-hn/ +├── src/ +│ ├── app/ +│ │ ├── core/ # Core module (header, footer, settings) +│ │ │ ├── footer/ +│ │ │ ├── header/ +│ │ │ └── settings/ +│ │ ├── feeds/ # Feed-related components +│ │ │ ├── feed/ # Main feed list component +│ │ │ └── item/ # Individual feed item component +│ │ ├── item-details/ # Item details with comments (lazy-loaded) +│ │ │ └── comment/ +│ │ ├── user/ # User profile (lazy-loaded) +│ │ ├── shared/ # Shared resources +│ │ │ ├── components/ # Reusable components +│ │ │ ├── models/ # TypeScript interfaces/models +│ │ │ ├── pipes/ # Custom pipes +│ │ │ ├── scss/ # Shared styles +│ │ │ └── services/ # API and utility services +│ │ ├── app.component.ts # Root component +│ │ ├── app.module.ts # Root module +│ │ └── app.routes.ts # Application routing +│ ├── assets/ # Static assets +│ ├── environments/ # Environment configurations +│ └── index.html # Main HTML file +├── e2e/ # End-to-end tests +├── angular.json # Angular CLI configuration +├── firebase.json # Firebase hosting configuration +├── karma.conf.js # Karma test configuration +├── package.json # Project dependencies +└── tsconfig.json # TypeScript configuration +``` + +## Application Routes + +The application supports the following routes: -This app uses [Workbox](https://workboxjs.org/) to generate a service worker as part of the build step to load quickly and work offline. +| Route | Description | +|-------|-------------| +| `/news/:page` | Top stories from Hacker News | +| `/newest/:page` | Most recent stories | +| `/show/:page` | Show HN submissions | +| `/ask/:page` | Ask HN questions | +| `/jobs/:page` | Job postings | +| `/item/:id` | Individual story with comments | +| `/user/:id` | User profile page | -## Manifest +## API -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. +This application uses the [node-hnapi](https://github.com/cheeaun/node-hnapi) as its backend API, which provides a clean REST interface to Hacker News data. + +**Base URL**: `https://node-hnapi.herokuapp.com` + +### Endpoints + +| Endpoint | Description | +|----------|-------------| +| `/{feed}?page={n}` | Get feed items (news, newest, show, ask, jobs) | +| `/item/{id}` | Get item details with comments | +| `/user/{id}` | Get user profile | + +## PWA Features + +### Service Worker + +The application uses Angular's built-in service worker (`@angular/service-worker`) to provide offline capabilities. The service worker configuration is defined in `ngsw-config.json`. + +### Web App Manifest + +With Chromium-based browsers for Android (Chrome, Opera, etc.), the application includes a Web App Manifest that allows installation to your home screen.

- +

## Themes -Built in theme engine! +The application includes a built-in theme engine with the following themes: + +- **Default**: Light theme with orange accents +- **Night**: Dark theme for low-light environments +- **Black**: Pure black theme optimized for AMOLED displays + +## Testing + +### Unit Tests + +Run unit tests with Karma: +```bash +npm test +``` -Current themes: -* Default -* Night -* Black (AMOLED) +### End-to-End Tests -More to come! +Run E2E tests with Protractor: +```bash +npm run e2e +``` -## Areas of improvement +## Deployment - - 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 +The application is configured for deployment to Firebase Hosting. -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. +### Deploy to Firebase -## Build process +1. Install Firebase CLI: +```bash +npm install -g firebase-tools +``` -Note: This project has been ejected (with AOT + production settings) in order to customize Webpack configurations. +2. Login to Firebase: +```bash +firebase login +``` - - 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/`) +3. Build the application: +```bash +npm run build +``` -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) +4. Deploy: +```bash +firebase deploy +``` + +### CI/CD + +The project uses Travis CI for continuous integration and deployment. On every push to the `master` branch, Travis CI will build the application and deploy to Firebase Hosting if the build succeeds. + +## Areas for Improvement + +- Realtime updating using the Firebase SDK +- Server-side rendering for improved SEO and initial load performance + +## Contributing + +Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests. + +## License + +This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details. ## 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) +A million thanks to these 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) + +## Feedback + +Feel free to send feedback on [Twitter](https://twitter.com/hdjirdeh) or [file an issue](https://github.com/COG-GTM/angular2-hn/issues/new). Feature requests are always welcome!