175 lines
4.6 KiB
Markdown
175 lines
4.6 KiB
Markdown
# Koko Blog
|
|
|
|
A fast, beautiful personal blog built with React, TypeScript, and a synthwave purple theme.
|
|
|
|
**Load time target:** < 100ms | **Bundle target:** < 50KB initial JS (gzipped) | **Rendering approach:** static-first + minimal runtime JS
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
- **Framework:** React 19 + TypeScript
|
|
- **Build tool:** Vite (fast dev server + optimized production bundles)
|
|
- **Routing:** React Router with route-level code splitting
|
|
- **Content:** Markdown posts validated by Zod at build time
|
|
- **Syntax highlighting:** Shiki at build time (no heavy client runtime highlighter)
|
|
- **Image optimization:** `node scripts/optimize-images.mjs` (WebP + size variants via sharp)
|
|
- **Package manager:** pnpm
|
|
|
|
> **For AI agents:** This project is React-first. Use `.tsx` components and standard React patterns.
|
|
> Do not create non-React template formats. Keep dependencies lean and avoid heavy UI frameworks.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev # dev server at http://localhost:5173
|
|
pnpm build # production build -> dist/
|
|
pnpm preview # preview production build
|
|
pnpm typecheck # TypeScript check (tsc --noEmit)
|
|
```
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
koko-blog/
|
|
├── public/
|
|
│ ├── images/
|
|
│ │ ├── posts/ # Original post images
|
|
│ │ └── previews/ # Optimized WebP variants
|
|
│ └── favicon.svg
|
|
├── src/
|
|
│ ├── app/
|
|
│ │ ├── App.tsx
|
|
│ │ └── routes.tsx # Route config + lazy loading
|
|
│ ├── components/
|
|
│ │ ├── layout/
|
|
│ │ │ ├── Layout.tsx
|
|
│ │ │ ├── Header.tsx
|
|
│ │ │ ├── Sidebar.tsx
|
|
│ │ │ └── Footer.tsx
|
|
│ │ ├── Hero.tsx
|
|
│ │ ├── PostCard.tsx
|
|
│ │ └── PostGrid.tsx
|
|
│ ├── pages/
|
|
│ │ ├── HomePage.tsx
|
|
│ │ ├── PostPage.tsx
|
|
│ │ └── NotFoundPage.tsx
|
|
│ ├── content/
|
|
│ │ ├── config.ts # Zod schema for post frontmatter
|
|
│ │ └── blog/ # Markdown posts (.md files)
|
|
│ ├── styles/
|
|
│ │ ├── synthwave.css # Theme tokens + gradients
|
|
│ │ └── global.css # Reset + base styles
|
|
│ ├── lib/
|
|
│ │ ├── content.ts # Build-time content loading helpers
|
|
│ │ └── date.ts # Date formatting utilities
|
|
│ └── main.tsx
|
|
├── scripts/
|
|
│ └── optimize-images.mjs
|
|
├── vite.config.ts
|
|
├── tsconfig.json
|
|
├── README.md
|
|
└── TODO.md
|
|
```
|
|
|
|
---
|
|
|
|
## Scripts
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `pnpm dev` | Start Vite dev server |
|
|
| `pnpm build` | Build production assets |
|
|
| `pnpm preview` | Preview production build |
|
|
| `pnpm typecheck` | Run TypeScript checks |
|
|
| `pnpm lint` | Lint codebase |
|
|
| `node scripts/optimize-images.mjs` | Convert and resize images before build |
|
|
|
|
---
|
|
|
|
## Design System
|
|
|
|
### Colors
|
|
|
|
| Token | Hex | Usage |
|
|
|-------|-----|-------|
|
|
| Primary | `#6a1b9a` | Buttons, accents, links |
|
|
| Primary Dark | `#510ca9` | Hover states |
|
|
| Secondary | `#000080` | Electronic sheen elements |
|
|
| Background | `#000000` | Page background |
|
|
| Paper | `#121212` | Card backgrounds |
|
|
| Text Primary | `#ffffff` | Headings |
|
|
| Text Secondary | `#eeeeee` | Body text |
|
|
| Text Muted | `#888888` | Metadata |
|
|
|
|
### Typography
|
|
|
|
- **Headlines:** 2.5rem-4rem, weight 800
|
|
- **Titles:** 1.8rem, weight 700
|
|
- **Body:** 1rem, line-height 1.8
|
|
- **Code:** Monospace, dark theme blocks (Shiki)
|
|
|
|
### Breakpoints
|
|
|
|
- **Mobile:** < 768px
|
|
- **Tablet:** 768px-1024px
|
|
- **Desktop:** > 1024px
|
|
|
|
---
|
|
|
|
## Writing Content
|
|
|
|
Posts live in `src/content/blog/` as `.md` files with YAML frontmatter:
|
|
|
|
```markdown
|
|
---
|
|
title: "My Awesome Post"
|
|
slug: "my-awesome-post"
|
|
excerpt: "A brief description..."
|
|
publishedAt: "2026-02-28"
|
|
category: "Game Development"
|
|
tags: ["unity", "csharp"]
|
|
image: "/images/posts/hero.jpg"
|
|
draft: false
|
|
---
|
|
|
|
Your content here with **markdown** support.
|
|
```
|
|
|
|
---
|
|
|
|
## TypeScript Path Aliases
|
|
|
|
```typescript
|
|
import Layout from '@components/layout/Layout';
|
|
import '@styles/global.css';
|
|
```
|
|
|
|
Available aliases (defined in `tsconfig.json`):
|
|
- `@/*` -> `./src/*`
|
|
- `@components/*` -> `./src/components/*`
|
|
- `@pages/*` -> `./src/pages/*`
|
|
- `@styles/*` -> `./src/styles/*`
|
|
- `@lib/*` -> `./src/lib/*`
|
|
|
|
---
|
|
|
|
## Performance Targets
|
|
|
|
| Metric | Target |
|
|
|--------|--------|
|
|
| Initial JS bundle | < 50KB (gzipped) |
|
|
| FCP | < 100ms (local baseline) |
|
|
| LCP | < 1.0s |
|
|
| CLS | < 0.1 |
|
|
| Lighthouse performance | > 90 |
|
|
|
|
---
|
|
|
|
**Built with:** React • TypeScript • Vite • pnpm
|