Hacker News Reader

An experimental Hacker News reader built with React, TypeScript, and modern tooling. Features parallax scrolling effects and a polished UX.

Overview

This project is a modern Hacker News reader that consumes data directly from the Hacker News Firebase REST API. It features:

• ✨ A parallax-like scrolling inspired in starwars
• ⚡ Lightning-fast development with Vite
• 🎨 Customizable themes via styled-components
• 📱 Responsive design
• 🔧 Full TypeScript support

Installation

npm install react-hn-reader styled-components

Peer dependencies: react >=16.8 || >=17 || >=18 || >=19, react-dom >=16.8 || >=17 || >=18 || >=19, styled-components >=5.0 || >=6.0

Quick Start

Important: You must include DefaultStyles for proper typography and styling:

import { HackerNewsReader, ThemeProvider, DefaultStyles } from 'react-hn-reader'

function App() {
  return (
    <ThemeProvider>
      <DefaultStyles />
      <HackerNewsReader />
    </ThemeProvider>
  )
}

✅ Fonts are loaded automatically - Google Fonts (Bitter, Work Sans, Nanum Gothic) are injected dynamically when the component mounts.

Features

• ✨ Parallax scrolling - 3D depth effect with three viewport layers
• 🖱️ Scroll indicator - Animated mouse icon in top-right (fades on scroll)
• 🖤 Fixed black logo - Appears at bottom-right when scrolling down
• ➡️ Arrow icons - Each story displays an arrow-out icon
• 🎨 Customizable themes - Override all colors via ThemeProvider
• 🔧 TypeScript - Full type support

Props

Usage Examples

Custom Theme

<ThemeProvider theme={{ orange: '#ff4500', onyx: '#1a1a1a' }}>
  <DefaultStyles />
  <HackerNewsReader />
</ThemeProvider>

Custom API

<HackerNewsReader 
  apiUrl="https://your-api.com/v0"
  initialCount={50}
/>

Handle Clicks

<HackerNewsReader 
  onStoryClick={(story) => console.log(story.title)}
/>

Self-Contained Mode (Astro, iframes, overflow: hidden)

When the component is used in a parent container with overflow: hidden (like Astro.js with scoped styles) or inside an iframe, the parallax scrolling won't work because the window can't scroll. Use selfContained mode to create an internal scrollable container:

// For Astro.js or any container with overflow: hidden
<HackerNewsReader selfContained={true} />

// Custom scroll container height (default is 100vh)
<HackerNewsReader 
  selfContained={true} 
  scrollContainerHeight="600px" 
/>

// Or use a number for pixels
<HackerNewsReader 
  selfContained={true} 
  scrollContainerHeight={800} 
/>

When to use self-contained mode:

• Astro.js: When the page has scoped styles with overflow: hidden
• iframes: When mounted inside an iframe for isolation
• Modals/Dialogs: When the component is inside a fixed container
• Overflow hidden parents: When any ancestor has overflow: hidden on html/body

Fonts

Google Fonts are loaded automatically when the component mounts:

• Bitter - Primary text font
• Work Sans - Headings
• Nanum Gothic - Author names

No manual configuration needed!

Development

npm install
npm run build    # Build package
npm run dev      # Development mode with example

Local Testing with Preview Build

Build a standalone preview version that bundles React and all dependencies:

npm run build:preview    # Build standalone preview to dist/preview/
npm run serve            # Serve with http-server on http://localhost:8080

Or manually:

npm run build:preview
npx http-server ./dist/preview -p 8080 -o

The preview build is a fully self-contained version that doesn't require external React dependencies, making it perfect for testing the component in isolation before publishing.

Build Everything

To build both the library and preview at once:

npm run build:all   # Builds preview first, then library

Publish

npm run build
npm publish