Hacker News Reader

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

⚠️ IMPORTANT: Installation Required

You MUST install via NPM. This package uses styled-components which requires proper bundling. CDN imports will NOT work correctly.

npm install @punkbit/react-hn-reader styled-components

Quick Start

Standard React Apps

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

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

Astro.js / SSR Frameworks

⚠️ Use ScopedDefaultStyles and selfContained mode:

// src/components/HNReader.tsx
import { 
  HackerNewsReader, 
  ThemeProvider, 
  ScopedDefaultStyles 
} from '@punkbit/react-hn-reader'

export default function HNReader() {
  return (
    <ThemeProvider>
      <div data-react-hn-reader style={{ height: '100vh' }}>
        <ScopedDefaultStyles />
        <HackerNewsReader 
          selfContained={true}
          scrollContainerHeight="100vh"
        />
      </div>
    </ThemeProvider>
  )
}

---
// src/pages/hn.astro
import HNReader from '../components/HNReader';
---

<html>
  <head><title>HN Reader</title></head>
  <body style="margin: 0;">
    <HNReader client:load />
  </body>
</html>

Why this is needed for Astro.js:

Astro adds scoped styles with overflow: hidden that break window scrolling
selfContained={true} creates an internal scrollable container
ScopedDefaultStyles prevents CSS from leaking to other parts of your app

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
📦 SSR Compatible - Works with Astro.js, Next.js, etc.

Props

Prop	Type	Default	Description
`apiUrl`	`string`	HN Firebase API	Base URL for stories API
`initialCount`	`number`	30	Initial stories to load
`enableLoadMore`	`boolean`	true	Show load more button
`onStoryClick`	`(story) => void`	-	Click handler
`selfContained`	`boolean`	false	Enable for SSR/Astro.js
`scrollContainerHeight`	`string \| number`	'100vh'	Scroll container height
`containerClassName`	`string`	-	CSS class for scroll container

Development

# Install dependencies
npm install

# Dev mode (normal)
npm run dev

# Build library
npm run build

# Build preview
npm run build:preview

# Test preview locally
npm run serve

JSPM

@punkbit/react-hn-reader

Package Exports

Readme