HackerNew

What if HN was built today?
A modern, open-source reimagining of Hacker News

Live Demo • Quick Start • Features • Contributing

---

We use Hacker News every single day. It's one of the best communities on the internet.

This project is a love letter to that community — a "what if" exploration of what HN might feel like if it were built with a modern 2025 stack. We're not here to replace it or critique it. Just to imagine, learn, and share.

Why?

• To learn — Building real projects is the best way to learn modern web development
• To explore — What does "modern" actually mean for a content-focused site?
• To share — Maybe some ideas here spark inspiration for others

HackerNew is intentionally minimal. No algorithmic feeds. No engagement hacking. Just content, presented cleanly.

---

Quick Start

Three commands. That's it.

# 1. Clone
git clone https://github.com/meysam81/hackernew.git && cd hackernew

# 2. Install (requires Bun - see below if needed)
bun install

# 3. Run
bun dev

Open localhost:4321/hackernew and you're in.

Don't have Bun?

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

# Or via npm
npm install -g bun

---

Features

For Readers

Feature	Description
Dark/Light Mode	Respects system preference, toggle anytime
Keyboard Navigation	j/k to move, o to open, c for comments
Bookmarks	Save stories for later (syncs with account)
Reading History	Keep track of what you've read
Density Toggle	Comfortable or compact view

For Developers

Feature	Description
Island Architecture	Static pages, hydrated components
Type-Safe	Full TypeScript throughout
Modern CSS	Tailwind v4 with design tokens
Auth Ready	Supabase OAuth (GitHub/Google)
Zero Config Deploy	Works on any static host

Keyboard Shortcuts

j / k       Navigate stories
o           Open story link
c           Open comments
b           Toggle bookmark
Esc         Go back

---

Tech Stack

We picked tools we enjoy using:

• Astro — Fast by default, islands architecture
• Vue 3 — Reactive components with Composition API
• Tailwind CSS v4 — Utility-first styling
• Supabase — Auth + Postgres (optional)
• Bun — Fast runtime and package manager

The official Hacker News API powers all the content.

---

Project Structure

src/
├── components/
│   ├── auth/           # Login, user menu
│   ├── story/          # Feed, items, details
│   ├── comment/        # Threaded comments
│   └── ui/             # Buttons, skeletons
├── composables/        # Shared Vue logic
│   ├── useAuth.ts
│   ├── useTheme.ts
│   ├── useBookmarks.ts
│   └── useKeyboard.ts
├── lib/
│   ├── hn-client.ts    # HN API with caching
│   └── supabase.ts     # Auth client
├── pages/              # File-based routes
│   ├── index.astro     # Top stories
│   ├── new.astro       # New stories
│   ├── ask.astro       # Ask HN
│   ├── show.astro      # Show HN
│   └── item/[id].astro # Story details
└── styles/
    └── global.css      # Design tokens

---

Configuration

Basic Setup (No Auth)

Works out of the box! Just bun dev and go.

With Authentication

Want bookmarks that sync across devices? Set up Supabase:

1. Create a project at supabase.com

2. Run the schema — Copy supabase/schema.sql into the SQL Editor

3. Enable OAuth — In Authentication → Providers, enable GitHub and/or Google

4. Add your credentials:

   cp .env.example .env

   PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   PUBLIC_SUPABASE_ANON_KEY=your-anon-key

5. Configure URLs — In Authentication → URL Configuration:

   • Site URL: http://localhost:4321/hackernew
   • Redirect URLs: http://localhost:4321/hackernew/auth/callback

---

Deployment

GitHub Pages (Automatic)

Push to main and the included GitHub Action handles it:

1. Go to Settings → Pages
2. Set Source to "GitHub Actions"
3. (Optional) Add secrets for auth: PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_ANON_KEY

Any Static Host

bun run build
# Upload dist/ to Vercel, Netlify, Cloudflare Pages, anywhere

Custom Domain

Update astro.config.mjs:

export default defineConfig({
  site: "https://your-domain.com",
  base: "/", // Remove /hackernew if using root domain
  // ...
});

---

Contributing

We'd love your help! Here's how to get started:

1. Fork the repo
2. Create a branch: git checkout -b my-feature
3. Make your changes
4. Test locally with bun dev
5. Push and open a PR

Ideas for Contributions

• RSS feed generation
• Offline support (PWA)
• Story sharing cards
• Comment collapse persistence
• Search functionality
• i18n support

Not sure where to start? Look for issues labeled good first issue.

---

Design Philosophy

HackerNew follows a few principles:

1. Content first — UI should enhance reading, not distract
2. Speed matters — Static generation + minimal JS = fast loads
3. Respect preferences — Dark mode, density, keyboard users
4. Progressive enhancement — Works without JS, better with it

The design takes cues from tools we admire: Linear's clarity, Vercel's simplicity, Raycast's keyboard-first approach.

---

FAQ

Why not just use the official HN site?

You should! The official site is great and we use it daily. This is just a learning project and design exploration.

Will this replace my HN workflow?

Probably not, and that's okay. It's meant for exploring what's possible, not replacing what works.

Can I deploy my own instance?

Absolutely! That's the whole point. Fork it, customize it, make it yours.

Why Bun instead of npm/yarn/pnpm?

Speed, mostly. But the project works with any package manager — just replace bun with your preferred tool.

---

Acknowledgments

• Hacker News — For 18+ years of thoughtful discussion
• HN API — For making this possible
• Everyone who reads HN — You're what makes the community great

---

License

Apache 2.0 — Use it, learn from it, build on it.

---

_{Built with care for the HN community}
hackernew.dev