🪻Niko Waves

A modern anime watching platform built with Next.js, React, Hono, Bun, Firebase, and a custom HiAnime-compatible content API. Niko Waves provides anime discovery, search, detail pages, SUB/DUB episode playback, favorites, watchlist tracking, comments, and a responsive light/dark interface.

Overview | Features | Technology | Structure | Getting Started | Configuration | API Summary | Screenshots | License

💜 Overview

Niko Waves is a full-stack anime streaming and discovery web application. The project is divided into two main applications:

• site/ contains the Next.js frontend, anime UI, watch player, Firebase authentication, watchlist/favorites, comments, theme system, and public pages.
• api/ contains a Bun-powered Hono API that fetches and normalizes anime catalog, episode, server, stream, character, actor, search, and genre data.

The frontend consumes /api/v1 endpoints from the backend and uses Firebase for user-specific data such as Google sign-in, favorites, watch statuses, comments, likes, replies, and view-related data. The result is a media-focused application with a streaming-style interface and personalized anime tracking features.

💜 Features

• Homepage spotlight, trending carousel, rankings, genres, and category browsing.
• Search suggestions, search results, responsive navigation, and SEO support.
• Anime detail pages with synopsis, metadata, recommendations, and character previews.
• Watch pages with SUB/DUB switching, server switching, episode controls, and episode lists.
• Firebase auth, favorites, watchlist tracking, comments, replies, likes, and realtime updates.
• Light/dark mode, responsive layouts, Framer Motion animations, and Swiper carousels.
• Bun-powered Hono API with rate limiting, logging, Swagger docs, and optional Redis caching.

💜 Technology Stack

Layer	Technologies
Frontend	Next.js 15, React 19, App Router
UI and Styling	Tailwind CSS 4, Framer Motion, Swiper, React Icons, next-themes
Data Fetching	TanStack React Query, SWR, Axios, Fetch API
Video/Streaming	iframe-based stream embeds, HLS-related dependencies, Vidstack/HLS support libraries
User Data	Firebase Authentication, Cloud Firestore
State	Zustand stores for genres and top-ten data
Backend API	Hono, Bun runtime
Scraping/Parsing	Axios, Cheerio, aniwatch package, custom extractors
API Protection	CORS, Hono rate limiter
API Docs	Swagger UI and OpenAPI JSON
Deployment Support	Vercel config for API, Next.js production build

💜 System Design

Niko Waves follows a layered client-server architecture. The frontend is responsible for presentation, navigation, and personalized user interaction. The backend API is responsible for collecting, transforming, and serving anime catalog and streaming metadata. Firebase provides identity and user-owned state.

flowchart LR
    User["User Browser"] --> Site["Next.js Frontend"]
    Site -->|"Catalog/search/watch requests"| API["Hono API on Bun"]
    API -->|"Scrape/normalize"| Source["Anime content sources"]
    Site -->|"Google sign-in"| Auth["Firebase Auth"]
    Site -->|"Favorites, watchlist, comments"| Firestore["Cloud Firestore"]
    Site -->|"Embedded playback"| Player["Stream Provider Embed"]
    API --> Docs["Swagger/OpenAPI Docs"]

Loading

• Frontend layer: Next.js pages and components handle the UI and user flow.
• API layer: Hono routes serve catalog, search, episodes, servers, streams, and genres.
• Data layer: backend extractors normalize upstream anime data into structured JSON.
• User layer: Firebase Authentication and Firestore store favorites, watchlist data, and comments.

💜 Project Structure

niko-waves/
├── README.md
├── LICENSE
├── banner.jpg
├── demo/
│   └── video.mp4
├── screenshots/
│   ├── dark/
│   └── light/
├── api/
│   ├── index.js
│   ├── package.json
│   ├── vercel.json
│   ├── http/
│   └── src/
│       ├── app.js
│       ├── config/
│       ├── controllers/
│       ├── extractor/
│       ├── parsers/
│       ├── routes/
│       ├── services/
│       └── utils/
└── site/
    ├── package.json
    ├── next.config.mjs
    ├── eslint.config.mjs
    ├── postcss.config.mjs
    ├── public/
    └── src/
        ├── app/
        ├── components/
        ├── data/
        ├── lib/
        ├── store/
        ├── styles/
        └── utils/

💜 Getting Started

Prerequisites

• Node.js 20 or newer for the Next.js app.
• npm for frontend dependency installation.
• Bun for the backend API.
• Firebase project with Authentication and Firestore enabled.

1. Install Frontend Dependencies

cd site
npm install

2. Install Backend Dependencies

cd ../api
bun install

3. Configure Environment Variables

Create .env.local inside site/ and .env inside api/. See the next section for the variables used by the codebase.

4. Run the API

cd api
bun run dev

The API runs on http://localhost:3030.

5. Run the Frontend

cd site
npm run dev

The frontend runs on http://localhost:3000.

💜 Configuration

Frontend: site/.env.local

NEXT_PUBLIC_API_URL=http://localhost:3030
NEXT_PUBLIC_BASE_URL=http://localhost:3000

NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id

Backend: api/.env

BASE_URL=http://localhost:3030
ORIGIN=http://localhost:3000

RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_LIMIT=100

UPSTASH_REDIS_REST_URL=optional_upstash_url
UPSTASH_REDIS_REST_TOKEN=optional_upstash_token

💜 Available Scripts

Frontend

Command	Description
npm run dev	Start the Next.js development server with Turbopack.
npm run build	Build the production frontend.
npm start	Start the built frontend.
npm run lint	Run Next.js linting.

Backend

Command	Description
bun run dev	Start the API in watch mode.
bun run start	Start the API normally.
bun run lint	Run ESLint.
bun run lint:fix	Run ESLint fix and Prettier formatting.
bun run test	Run the configured Vitest command.

💜 API Summary

The backend API is mounted under /api/v1.

Endpoint	Description
GET /api/v1	API documentation response.
GET /api/v1/home	Homepage data including spotlight, trending, top airing, latest episodes, top 10, and genres.
GET /api/v1/anime/:id	Anime detail page data.
GET /api/v1/animes/:query/:category?	List pages such as top airing, most popular, genre, movie, TV, OVA, ONA, special, and A-Z.
GET /api/v1/search?keyword=&page=	Anime search results.
GET /api/v1/suggestion?keyword=	Search suggestions for the header search UI.
GET /api/v1/characters/:id	Characters and voice actors for an anime.
GET /api/v1/character/:id	Character or actor detail data.
GET /api/v1/episodes/:id	Episode list for an anime.
GET /api/v1/servers?id=	Available servers for an episode.
GET /api/v1/stream?id=&type=&server=	Stream source metadata for an episode.
GET /api/v1/genres	Supported genre list.
GET /doc	OpenAPI JSON.
GET /ui	Swagger UI.
GET /ping	Health check.

💜 Frontend Routes

Route	Purpose
/	Homepage with spotlight, rankings, lists, and genres.
/search?keyword=	Search results.
/info/[id]	Anime detail page.
/watch/[id]	Episode player and comments.
/list/[type]	Category/list pages.
/list/[type]/[char]	A-Z list filtering.
/favorites	User favorites from Firestore.
/watchlist	User anime tracking list from Firestore.
/characters/[id]	Anime character list.
/character/[id]	Character detail page.
/actor/[id]	Actor/voice actor detail page.

💜 Firebase Data Usage

Niko Waves uses Firebase for user-owned data rather than storing it in the scraper API:

• users/{uid}.favorites stores favorited anime by anime ID.
• users/{uid}.statuses stores watchlist status by anime ID.
• anime/{animeId}/episodes/{episodeNumber}/comments stores episode comments, replies, likes, and author snapshots.
• animeViews is used by the local views API routes for view count style data.

💜 Screenshots

The project includes screenshots in the base screenshots/ directory.

Light Theme
Home	Anime Info	Anime Watch
Dark Theme
Home	Anime Info	Anime Watch

💜 Deployment Notes

• Deploy the site/ folder as the frontend application.
• Deploy the api/ folder as the backend service with Bun support.
• Set NEXT_PUBLIC_API_URL on the frontend to the deployed API base URL.
• Set ORIGIN on the API to the frontend domain for stricter CORS.
• Configure Firebase authorized domains for local and production frontend URLs.
• Use rate limiting and optional Redis caching in production to reduce upstream load.

💜 Legal and Usage Notice

This project is intended for educational and portfolio purposes. If deployed publicly, ensure that all content access, streaming links, metadata usage, and third-party provider integrations comply with applicable laws, content licenses, and provider terms of service.

💜 License

This project is licensed under the MIT License. See LICENSE for details.

💜 Author

Ashish Kumar

💜 Credits

This project builds upon and adapts the excellent HiAnime API by yahyaMomin. The backend API implementation in api/ is based on:

• HiAnime API — https://github.com/yahyaMomin/hianime-API

Significant modifications and additional features have been made for this project, including: Special thanks to yahyaMomin for making the original project open source.