comics.banast.as

comics.banast.as

[Live site] [CI] [License: MIT]

A public, responsive catalog for browsing a personal comic-book collection. It combines collection search, storage organization, grading and value analytics, clean shareable routes, and a read-only API in one static-first React application.

[Current comics.banast.as collection overview]

Live collection overview captured September 1, 2026.

Highlights

• Browse the collection as a cover grid or compact list.
• Search titles, series, artists, notes, and signatures.
• Sort and filter by release date, issue number, grade, price, value, condition, and variant status.
• Explore dedicated pages for comics, series, cover artists, computed tags, storage boxes, raw comics, slabbed comics, and variants.
• Review acquisition, grade, value, and collection-health analytics.
• Share clean canonical URLs while preserving old hash-route bookmarks.
• Consume the same checked-in collection through read-only Cloudflare Pages Functions.

Visit the production site at comics.banast.as.

How it works

The browser experience is a React and TypeScript app built with Vite and styled with Tailwind CSS. Zustand owns application state, Zod validates collection records, and Vitest covers routing, data contracts, accessibility guardrails, API behavior, and generated public files.

The production build adds a static entry page for every public route. Each page includes route-specific titles, descriptions, canonical URLs, Open Graph and Twitter metadata, JSON-LD, and crawlable fallback content before React hydrates. Cloudflare Pages serves the generated files and the functions in functions/api/.

src/data/comics.json is the shared source for the UI, sitemap, generated pages, and API. A collection update therefore requires a validated build and deployment.

Quick start

Requirements:

• Node.js 20.19 or newer, with Node.js 24 LTS recommended
• npm 11

git clone https://github.com/banastas/comics.banast.as.git
cd comics.banast.as
npm ci
npm run dev

Open http://localhost:5173.

To start with the small demonstration dataset instead of the public collection:

cp example-comic-collection.json src/data/comics.json
npm run dev

Commands

npm run check is the authoritative pre-merge and pre-deploy command. public/sitemap.xml is derived output and is not tracked in git: npm run generate:sitemap and npm run build regenerate it from the collection, so a collection sync never leaves a stale sitemap in the repository.

Repository map

src/
├── components/          React views and reusable UI
├── data/comics.json     Canonical collection data
├── hooks/               Routing and scroll behavior
├── stores/              Zustand application state
├── types/Comic.ts       Shared collection types
├── utils/               Routing, analytics, accessibility, and formatting
└── validation/          Zod collection schema
functions/api/           Read-only Cloudflare Pages API
scripts/                 Data, sitemap, static-page, and release checks
public/                  Icons, manifest, headers, robots, and 404 (sitemap.xml is generated here, untracked)
docs/                    Architecture notes and repository images

Data contract

Each collection record follows the Comic interface in src/types/Comic.ts. Before committing synced or hand-edited data, run:

npm run check

The checks reject malformed records, duplicate IDs, duplicate public slugs, sitemap and static-page drift, missing public assets, and API incompatibilities. npm run validate:data also prints a non-failing WARNINGS section with record IDs for data to fix in the source app, such as purchase dates before release dates, inconsistent series or artist spellings, raw 9.8+ grades, records without any price, and placeholder covers. Do not commit credentials or private collection data. Cover images are referenced by URL and are not copied into this repository.

The root example-comic-collection.json provides a small self-hosting example without replacing the live collection contract.

Public API

Cloudflare Pages Functions expose read-only JSON endpoints:

• GET /api/comics
• GET /api/comics?series=Alien
• GET /api/comics?artist=Jock
• GET /api/comics?q=signature
• GET /api/comics?limit=50&offset=100
• GET /api/comics/stats
• HEAD and OPTIONS on both endpoints

The collection endpoint supports series, artist, and text-query filters, plus optional limit (1–1000) and offset pagination applied after filtering. Responses include count (records in this response), total (matching records), offset, limit, and comics; without pagination parameters every matching record is returned. Invalid parameters return a JSON 400, and other methods return 405. Both endpoints return CORS, security, and short-lived cache headers for read-only clients.

Cover thumbnails

Covers are served full size from covers.banast.as. If Cloudflare Image Transformations are enabled for the zone, build with VITE_COVER_RESIZE=cloudflare to serve resized, modern-format thumbnails with srcset through /cdn-cgi/image. Without the variable the original files are used unchanged.

Routes and SEO

Canonical routes include:

• /collection and /stats
• /comic/:slug
• /series/:slug
• /artist/:slug
• /tag/:slug
• /storage/:slug and /boxes
• /raw, /slabbed, and /variants

Legacy /#/... links are normalized to the matching clean route. The build generates a sitemap and a static HTML entry for every public route, then verifies that metadata, structured data, assets, and fallback content are present. /collection renders the same view as /, so its page declares https://comics.banast.as/ as canonical and the sitemap lists only /.

See SEO.md for the current rendering contract and docs/ssr-migration-prd.md for the longer-term rendering roadmap.

Deployment

npm run check

For release QA, start Cloudflare's local Pages runtime with the built assets and Functions, then run the HTTP gate against that preview:

npx wrangler pages dev dist --port 5198 --compatibility-date 2026-07-17
# In a second terminal:
npm run verify:http -- http://127.0.0.1:5198

The HTTP gate catches asset-path and redirect failures that file-existence checks cannot detect. After an authorized deployment, run it again with https://comics.banast.as as the origin.

Deploy dist/ to Cloudflare Pages with functions/ available to the Pages project. No application environment variables are required. The checked-in _headers file supplies security and cache headers, and 404.html prevents unknown routes from returning a misleading SPA success response.

Browsing and statistics

Search, view, sort, and computed-tag filters travel with navigation URLs. Detail lists show 48 comics per page, and list pagination is available above and below the results. Missing purchase prices display as unrecorded; returns and series performance use only comics with both a recorded purchase price and a current value. The dashboard states that coverage explicitly.

The latest full QA findings and verification evidence are in docs/qa-2026-10-17.md.

Contributing and security

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Report vulnerabilities through the process in .github/SECURITY.md.

License

MIT