srrexus/komicastapi

<div align="center">

📚 Komikcast API

A fast, free, and open-source REST API for manga data

    

Live Demo · API Explorer · Report Bug

</div>

✨ Features

• —🚀 Blazing Fast — Responses are aggressively cached on the Edge (5 min to 7 days)
• —🔑 API Key Support — Your own apps get unlimited access with a secret bypass key
• —🛡️ Rate Limited — Built-in per-IP rate limiting (60 req/min) to prevent abuse
• —🖼️ Image Proxy — Built-in proxy to bypass hotlinking and CORS restrictions
• —📖 Interactive Docs — API Explorer dashboard at /api
• —🌐 Cloudflare Bypass — CF Worker proxy to avoid 403 blocks on serverless platforms
• —📦 Self-Hostable — Deploy to Vercel or Hugging Face Spaces with one push

📦 API Endpoints

Base URL: https://your-deployment.vercel.app

Popular Categories

?category=best-manhwa
?category=best-manhua
?category=best-manga
?category=anime-adaptations
?category=trending

Response Format

All endpoints return structured JSON:

{
  "status": 200,
  "message": "Success",
  "data": { ... }
}

Rate Limiting

Bypass rate limit by sending your secret API key:

X-API-Key: your-secret-key

🛠️ Tech Stack

🚀 Self-Hosting Guide

Prerequisites

• —Node.js 22+
• —pnpm 11
• —A Vercel or Hugging Face account (both free)
• —A Cloudflare account (free)

1. Clone & Install

git clone https://github.com/Wakype/komikcast-api.git
cd komikcast-api
pnpm install

2. Configure Environment

cp .env.example .env.local

Edit .env.local:

# Required: Target manga site URL
MANGA_BASE_URL=https://be.komikcast.cc/

# Required for Vercel/HF deploy: Your CF Worker proxy URL
SCRAPER_PROXY_URL=https://your-worker.your-subdomain.workers.dev

# Optional: additional proxy fallbacks
SCRAPER_PROXY_URL_2=
SCRAPER_PROXY_URL_3=

# Optional: ScraperAPI key (alternative to CF Worker)
SCRAPER_API_KEY=

# Optional: Secret key for rate limit bypass
BYPASS_SECRET=your-super-secret-key

3. Deploy Cloudflare Worker

The deployment needs a Cloudflare Worker to bypass Cloudflare's IP blocking. The worker code is at cloudflare-worker/worker.js.

1. 1.Go to Cloudflare Dashboard → Workers & Pages → Create Worker
2. 2.Name it (e.g., komikcast-proxy) → click Deploy
3. 3.Click Edit Code → paste the contents of cloudflare-worker/worker.js
4. 4.In Worker Settings → Variables, add: BYPASS_SECRET = same value as your .env.local
5. 5.Click Deploy and copy the Worker URL → set it as SCRAPER_PROXY_URL

4. Run Locally

pnpm dev

Open http://localhost:3000 for the landing page, or http://localhost:3000/api for the API Explorer.

☁️ Deploy to Vercel

# Push to GitHub, then import in Vercel dashboard
# Or use Vercel CLI:
npx vercel

Set all environment variables in Vercel → Project → Settings → Environment Variables.

🤗 Deploy to Hugging Face Spaces

This project supports auto-deploy to Hugging Face Spaces via GitHub Actions.

1. Add Dockerfile to project root

FROM node:22-alpine AS builder

WORKDIR /app

RUN corepack enable

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

FROM node:22-alpine AS runner

WORKDIR /app
ENV NODE_ENV=production
ENV PORT=7860

RUN corepack enable

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static

EXPOSE 7860

CMD ["node", "server.js"]

2. Enable standalone output in next.config.ts

const nextConfig: NextConfig = {
  output: 'standalone',
};

3. Create a Hugging Face Space

1. 1.Login to huggingface.co → New Space
2. 2.Choose SDK: Docker
3. 3.Note your username and space-name

4. Get a Hugging Face Token

Go to huggingface.co/settings/tokens → New token → Role: Write

5. Add GitHub Secrets

Go to your GitHub repo → Settings → Secrets and variables → Actions → New repository secret

6. Add the GitHub Action

Add .github/workflows/deploy-huggingface.yml to your repo (see the workflow file included in this repo). Every push to main will automatically build and deploy to your Space.

🏗️ Architecture

┌──────────────────┐     ┌──────────────────┐     ┌────────────────┐
│   Your Frontend  │────→│   API Server     │────→│  CF Worker     │────→ Target Site
│   + X-API-Key    │     │  (Next.js)       │     │  (Proxy)       │     (komikcast)
│                  │     │  Rate Limiter    │     │  Trusted IPs   │
└──────────────────┘     └──────────────────┘     └────────────────┘
                               ↑
                          Random Users
                         (rate limited)

Why Cloudflare Worker? Vercel and Hugging Face serverless functions run on datacenter IPs that Cloudflare actively blocks. By routing requests through a CF Worker (which runs inside Cloudflare's own network), requests are treated as trusted.

📁 Project Structure

komikcast-api/
├── .github/
│   └── workflows/
│       └── deploy-huggingface.yml  # Auto-deploy to HF Spaces
├── app/
│   ├── api/               # API endpoints + Explorer UI
│   ├── legal/             # Legal pages (Terms, Privacy, DMCA)
│   └── page.tsx           # Landing page
├── cloudflare-worker/     # CF Worker proxy (deploy separately)
├── libs/                  # Scraper core (fetchAPI, fetchPage)
├── types/                 # TypeScript interfaces
├── utils/                 # Response helpers, cache utilities
├── Dockerfile             # For Hugging Face Spaces deployment
├── .env.example           # Environment variable template
└── AGENTS.md              # AI coding assistant guide

⚠️ Legal Disclaimer

This API is provided for educational purposes and personal projects only. The creator is not responsible for how you use the data. We do not host any manga, images, or copyrighted content. All content belongs to their respective copyright holders.

📝 License

MIT License

Made with ❤️ by waky.dev