Hono와 프로젝트 구조

src/
  index.ts                 # 경로 조합
  types.ts                 # 서버 바인딩 타입
  routes/products.ts       # 상품 URL과 응답
  routes/jobs.ts           # 정기 실행 경로
  middleware/session.ts    # 세션 확인
  views/layout.ts          # 공통 SSR 레이아웃
  services/                # 결제·실시간 등 업무 로직
  repositories/            # 규모가 커지면 DB 접근 분리
public/                    # 브라우저 JS·CSS·이미지
migrations/001_init.sql
tests/
wrangler.jsonc
tsconfig.json

npm init -y
npm install hono
npm install -D typescript esbuild wrangler @cloudflare/workers-types

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noEmit": true,
    "types": [
      "@cloudflare/workers-types"
    ],
    "lib": [
      "ES2022",
      "DOM"
    ],
    "skipLibCheck": true
  },
  "include": [
    "src/**/*.ts"
  ]
}

{
  "name": "docs-local-example",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-06",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "docs-local",
      "database_id": "00000000-0000-0000-0000-000000000001"
    }
  ]
}

export type AppEnv = {
  Bindings: { DB: D1Database; STORAGE: R2Bucket; SESSION_HASH_SALT: string };
  Variables: { identity: { user_id: string; session_hash: string } };
};

import { Hono } from 'hono';
import { HTTPException } from 'hono/http-exception';
import { products } from './routes/products';
import { jobs } from './routes/jobs';
import type { AppEnv } from './types';

const app = new Hono<AppEnv>();
app.route('/', products);
app.route('/jobs', jobs);
app.get('/health', (c) => c.json({ ok: true }));
app.notFound((c) => c.text('페이지를 찾을 수 없습니다.', 404));
app.onError((error, c) => {
  if (error instanceof HTTPException) return error.getResponse();
  // 원문 요청·쿠키·PG 응답 대신 별도 오류 ID를 기록합니다.
  const errorId = crypto.randomUUID();
  console.error('request_failed', errorId);
  return c.json({ error: 'internal_error', errorId }, 500);
});
export default app;

import { html } from 'hono/html';

export function layout(title: string, description: string, body: ReturnType<typeof html>) {
  return html`<!doctype html>
<html lang="ko"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>${title}</title><meta name="description" content="${description}">
</head><body><header><a href="/">상품 목록</a></header>
<main>${body}</main></body></html>`;
}

import { Hono } from 'hono';
import { html } from 'hono/html';
import { layout } from '../views/layout';
import type { AppEnv } from '../types';
type Product = { id: number; name: string; description: string; price: number };
export const products = new Hono<AppEnv>();

products.get('/', async (c) => {
  const raw = c.req.query('after') || '0';
  if (!/^\d{1,15}$/.test(raw)) return c.text('잘못된 커서입니다.', 400);
  const after = Number(raw);
  const { results } = await c.env.DB.prepare(
    'SELECT id,name,description,price FROM products WHERE published=1 AND id>? ORDER BY id LIMIT 21'
  ).bind(after).all<Product>();
  const rows = results.slice(0, 20);
  const next = results.length > 20 ? rows[rows.length - 1].id : null;
  // html은 문자열 값을 이스케이프합니다. 사용자 입력을 raw()에 넣지 마세요.
  const body = html`<h1>상품 목록</h1><ul>${rows.map(p =>
    html`<li><a href="/products/${p.id}">${p.name}</a> · ${p.price}원</li>`
  )}</ul>${next === null ? '' : html`<a href="/?after=${next}">다음 페이지</a>`}`;
  c.header('Cache-Control', 'no-cache');
  return c.html(layout('상품 목록', '상품과 가격을 확인하세요.', body));
});

products.get('/products/:id', async (c) => {
  const id = c.req.param('id');
  if (!/^\d{1,15}$/.test(id)) return c.notFound();
  const p = await c.env.DB.prepare(
    'SELECT id,name,description,price FROM products WHERE id=? AND published=1'
  ).bind(Number(id)).first<Product>();
  if (!p) return c.notFound();
  c.header('Cache-Control', 'no-cache');
  return c.html(layout(p.name, p.description,
    html`<article><h1>${p.name}</h1><p>${p.description}</p><p>${p.price}원</p></article>`));
});

import { Hono } from 'hono';
import type { AppEnv } from '../types';
export const jobs = new Hono<AppEnv>();

jobs.post('/cleanup-sessions', async (c) => {
  // 스케줄러는 비공개 Dispatch 호출로 이 URL을 전달합니다.
  // X-JoripSpace-Cron-ID 같은 공개 헤더만으로 허용하면 안 됩니다.
  if (new URL(c.req.url).hostname !== 'joripspace-cron.internal')
    return c.json({ error: 'scheduler_required' }, 403);
  const result = await c.env.DB.prepare(
    'DELETE FROM app_sessions WHERE session_hash IN (' +
    'SELECT session_hash FROM app_sessions WHERE expires_at<=? ORDER BY expires_at LIMIT 100)'
  ).bind(Date.now()).run();
  // 반복 실행해도 안전하며, 남은 항목은 다음 스케줄에서 처리합니다.
  return c.json({ ok: true, deleted: result.meta.changes });
});

CREATE TABLE products (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT NOT NULL,
  price INTEGER NOT NULL CHECK(price > 0),
  published INTEGER NOT NULL DEFAULT 0 CHECK(published IN (0,1))
);
CREATE INDEX idx_products_public ON products(published,id);
INSERT INTO products(id,name,description,price,published)
VALUES(1,'예제 상품','SSR로 표시하는 공개 상품입니다.',1000,1);

CREATE TABLE app_sessions (
  session_hash TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  expires_at INTEGER NOT NULL
);
CREATE INDEX idx_sessions_expiry ON app_sessions(expires_at,session_hash);

npx wrangler d1 execute docs-local --local --file migrations/001_init.sql
npx tsc --noEmit
npx wrangler dev

npx esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/worker.js
joripspace db migrate --project PROJECT --file migrations/001_init.sql
joripspace deploy --project PROJECT --source dist/worker.js --label "Hono SSR 예제"