Last updated: 2026-02-15
This document defines code style, file organization, naming conventions, and development workflow for the Running Red project.
Guiding Principle: Consistency beats personal preference. Follow these conventions even if you disagree with specific choices.
These conventions are automatically enforced — violations will fail the build, lint, or commit hooks.
| Convention | Enforced by | Config file |
|---|---|---|
TypeScript strict mode (no any, strict null checks) |
TypeScript | tsconfig.json |
Extra strictness (noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch) |
TypeScript | tsconfig.json |
interface for object shapes (not type) |
ESLint | eslint.config.mjs |
No console.log (use console.warn/console.error if needed) |
ESLint | eslint.config.mjs |
No deep relative imports (../../*) — use @/ alias |
ESLint | eslint.config.mjs |
| Next.js best practices + Core Web Vitals | ESLint | eslint-config-next |
| TypeScript-specific lint rules | ESLint | eslint-config-next/typescript |
| Code formatting (semicolons, double quotes, trailing commas) | Prettier | .prettierrc.json |
| Tailwind class order | Prettier | prettier-plugin-tailwindcss |
Conventional commit messages (feat:, fix:, docs:, etc.) |
commitlint | commitlint.config.mjs |
| Pre-commit lint + typecheck | Husky | .husky/pre-commit |
You don't need to memorize these. If you violate a rule, the tooling will tell you.
These are judgment calls that can't be automated:
- Simplicity over cleverness — This is a webcomic site, not a SaaS platform. Prefer straightforward solutions.
- Don't over-abstract — Three similar lines of code is better than a premature abstraction.
- Documentation stays current — No phase is complete until docs in
docs/reflect the changes. - Be explicit — Implicit behavior is hard to debug. Prefer explicit, verbose code over clever shortcuts.
interface for object shapes (enforced by ESLint), type for unions and intersections (by convention):
// Object shape → interface
interface ComicPage {
id: number;
title: string | null;
status: Status;
}
// Union → type
type Status = "draft" | "published";nullfor database values that can be absent (maps to SQL NULL)undefinedfor optional function parameters or missing object properties
interface ComicPage {
title: string | null; // Database field, can be NULL
}
function renderPage(options?: { showTitle: boolean }) {
const showTitle = options?.showTitle ?? true; // undefined if not provided
}| Type | Casing | Example |
|---|---|---|
| React components | kebab-case | edit-comic-form.tsx, about-form.tsx |
| Utilities, hooks, libs | camelCase | formatDate.ts, useKeyboardNav.ts, db.ts |
| Next.js App Router files | lowercase (required by Next.js) | page.tsx, layout.tsx, error.tsx |
| Config files | standard names | tsconfig.json, package.json, .env.local |
running-red/
docs/ # Documentation (you are here)
public/ # Static assets
favicon.ico
robots.txt
images/
bg-flowers.png # Background image (Ren's design)
src/ # Source code
proxy.ts # Auth proxy (protects /admin/* routes)
app/ # Next.js App Router
layout.tsx # Root layout (minimal: html, body, fonts, globals)
globals.css # Ren's color palette + background via @theme inline
(public)/ # Public route group (reader-facing)
layout.tsx # Public layout (SiteHeader + SiteFooter)
page.tsx # Home page (latest published comic)
comic/
[slug]/
page.tsx # Individual comic page (ISR, generateStaticParams)
not-found.tsx # 404 for missing/unpublished comics
about/
page.tsx # About page (from about_page table)
archive/
page.tsx # Archive list (all published pages)
links/
page.tsx # External links (from links_page table)
rss.xml/
route.ts # RSS 2.0 feed (last 50 pages)
admin/ # Admin routes (protected by proxy.ts)
layout.tsx # Admin layout (nav, header, logout)
page.tsx # Admin dashboard
loading.tsx # Loading indicator for admin navigation
login/
page.tsx # Login form
comics/
page.tsx # List comics
new/
page.tsx # Add new comic
[slug]/
page.tsx # Edit comic (server component → EditComicForm)
about/
page.tsx # Edit About page (server component → AboutForm)
links/
page.tsx # Edit Links page (server component → LinksForm)
settings/
page.tsx # Edit Site Settings (server component → SettingsForm)
api/ # API routes
admin/
auth/
route.ts # Login/logout endpoints
comics/
route.ts # POST create comic (with FormData image)
[id]/
route.ts # PUT update / DELETE comic
about/
route.ts # GET/PUT about page
links/
route.ts # GET/PUT links page
settings/
route.ts # GET/PUT site settings
comics/
route.ts # GET public comics (published only)
images/
[...key]/
route.ts # R2 image proxy (immutable caching)
components/ # React components
admin/ # Admin-specific client components
about-form.tsx # About page form
edit-comic-form.tsx # Comic edit form
links-form.tsx # Links page form
settings-form.tsx # Settings page form
public/ # Public-facing components
ComicImage.tsx # Responsive <picture> with cache-busting
ComicNav.tsx # First/Prev/Next/Last + keyboard arrows
ComicPageView.tsx # Shared comic page layout + prefetch
ContentWarning.tsx # Blur overlay + reveal toggle
SiteHeader.tsx # Gold nav bar
SiteFooter.tsx # Copyright + RSS link
ui/ # Generic UI components (Phase 4)
db/ # Database files
schema.sql # Full schema (fresh install)
seed.sql # Default data seed
002-publish-timestamp.sql # Migration: DATE → TIMESTAMPTZ
lib/ # Utilities, helpers, clients
auth.ts # HMAC session auth utilities
db.ts # PostgreSQL client (pg Pool)
image.ts # Sharp image processing
r2.ts # R2 upload/download utilities
types.ts # TypeScript types
.env.local # Environment variables (not committed)
.env.example # Example env file (committed)
.gitignore
next.config.ts
tsconfig.json
package.json
README.md
Use @/ path alias for imports from src/ (configured in tsconfig.json, enforced by ESLint).
// Good
import { ComicPage } from "@/components/ComicPage";
import { db } from "@/lib/db";
// Will fail lint (deep relative path)
import { ComicPage } from "../../../components/ComicPage";Name props interfaces {ComponentName}Props and destructure props in the function signature.
interface ComicPageProps {
page: ComicPage;
showTitle?: boolean;
}
export function ComicPage({ page, showTitle = true }: ComicPageProps) {
return <div>{page.title}</div>;
}- Prefer Server Components (Next.js App Router default)
- Use
"use client"only when needed:- Component uses
useState,useEffect, or other React hooks - Component uses browser APIs (localStorage, window, etc.)
- Component has event handlers (
onClick,onSubmit, etc.)
- Component uses
Base styles are for mobile, then add breakpoints (sm:, md:, lg:).
<div className="w-full px-4 sm:px-6 md:w-3/4 md:px-8 lg:w-1/2">
{/* Mobile: full width → Tablet: 75% → Desktop: 50% */}
</div>If the same Tailwind classes appear 3+ times, extract into a reusable component.
- Tables:
snake_case(e.g.,comic_pages,site_settings) - Columns:
snake_case(e.g.,page_number,created_at) - Indexes:
idx_{table}_{column}(e.g.,idx_comic_pages_status)
// Good
const page = await db.query(
"SELECT * FROM comic_pages WHERE slug = $1",
[slug],
);
// NEVER do this (SQL injection risk)
const page = await db.query(
`SELECT * FROM comic_pages WHERE slug = '${slug}'`,
);main— Production (deployed to running.red)develop— Staging/integration (all PRs target this)- Feature branches —
feature/{name}orfix/{name}or descriptive names
- Create feature branch from
develop - Make changes, commit (conventional commits enforced by commitlint)
- Open PR to
develop - Review, merge
develop→mainfor production release (after testing)
Enforced by commitlint. Format: type: description
| Type | Use for |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation changes |
chore |
Maintenance (deps, config, etc.) |
refactor |
Code changes that don't add features or fix bugs |
style |
Formatting, whitespace (not CSS) |
test |
Adding or updating tests |
- Never push directly to
mainordevelop - All changes go through PRs
- PRs must pass CI (typecheck, lint, build) before merging
Don't catch-and-swallow errors. Let them propagate to error boundaries.
// Good — let error bubble to error.tsx boundary
export async function getComicPage(slug: string) {
const result = await db.query(
"SELECT * FROM comic_pages WHERE slug = $1",
[slug],
);
if (!result.rows[0]) {
throw new Error("Page not found");
}
return result.rows[0];
}Use Next.js error.tsx files at route level.
- Do comment: Complex logic, workarounds, TODOs
- Don't comment: Obvious code — use TypeScript types as documentation instead
Update docs/ when:
- Adding a feature →
PRODUCT.md,CONTENT_MODEL.md,IMPLEMENTATION.md - Changing architecture →
ARCHITECTURE.md,DECISIONS.md - Changing tech →
TECH_STACK.md,DECISIONS.md - Establishing patterns →
CONVENTIONS.md - Completing tasks →
IMPLEMENTATION.md
(Testing conventions will be added when tests are written)
Planned:
- Vitest for unit tests
- Playwright for E2E tests (if needed)
- Test files co-located with source:
ComicPage.test.tsxnext toComicPage.tsx
- TECH_STACK.md — Technologies used
- ARCHITECTURE.md — System design
- IMPLEMENTATION.md — Development roadmap