0

Remix full-stack trên Cloudflare Workers: frontend, backend, database và deploy trong một project

App chấm công nội bộ của mình viết bằng Remix, chạy trên Node. Để nó sống được cần cả một bộ: một server, Node đúng phiên bản, một file SQLite nằm trên ổ đĩa, một process chạy nền để đồng bộ dữ liệu, và ai đó nhớ cập nhật bản vá cho server. Với một tool nội bộ vài chục người dùng, phần "nuôi server" tốn công hơn cả phần viết code.

Cloudflare Workers đi theo hướng ngược lại: không có server để nuôi. Code chạy trên hạ tầng của Cloudflare, database là D1 (SQLite do Cloudflare quản lý), việc chạy nền là Cron Trigger, deploy là một lệnh. Bài này là hướng dẫn từng bước dựng một app chấm công mini theo cách đó: trang có form (frontend), loader và action đọc ghi database (backend), một API JSON có token, một job chạy theo lịch, và deploy lên Workers. Mọi lệnh và code trong bài mình đã chạy thử trên máy với Wrangler 4.164 và React Router 8.5. Phần cuối là bảng những gì phải đổi nếu bạn có sẵn một app Remix chạy Node như app của mình.

Trước tiên: Remix bây giờ tên là gì?

Chuyện đặt tên làm nhiều người bối rối, nên nói luôn cho rõ:

Bạn đang có Bây giờ dùng
Remix v2 (@remix-run/*) React Router (bản 7 trở lên, chế độ framework). Đây là bản kế tiếp của Remix v2, cùng loader, action, route theo file. Có hướng dẫn nâng cấp chính thức.
Muốn thử framework mới tên Remix 3 Remix 3 là một framework khác hẳn, không còn dựa trên React. Cloudflare có hướng dẫn riêng, nhưng hiện còn dùng nhiều gói bản beta và plugin bên thứ ba.

Bài này đi theo dòng thứ nhất: React Router, thứ mà Cloudflare gọi là "React Router (formerly Remix)". Ai đã viết Remix v2 sẽ thấy mọi thứ quen thuộc, chỉ khác tên gói.

Bước 1: tạo project

npm create cloudflare@latest -- cham-cong --framework=react-router

Lệnh này tạo project React Router, cài sẵn plugin Vite của Cloudflare và Wrangler (CLI để chạy và deploy Workers). Những file đáng chú ý:

cham-cong/
├── app/
│   ├── root.tsx            ← layout chung, giống Remix
│   ├── routes.ts           ← khai báo route
│   └── routes/home.tsx     ← một route: loader + action + component
├── workers/app.ts          ← điểm vào của Worker
├── wrangler.jsonc          ← cấu hình Worker: tên, binding, cron
└── vite.config.ts          ← plugin cloudflare() + reactRouter()

Chạy thử bằng npm run dev. Khác với Remix chạy Node, dev server ở đây chạy code server trong workerd, chính runtime mà Cloudflare dùng trên production. Nên thứ gì không chạy được trên Workers (ví dụ một thư viện cần module native của Node) sẽ lỗi ngay trên máy bạn, không phải đợi tới lúc deploy.

Bước 2: hiểu một request đi qua đâu

Trình duyệt
   │  GET /            POST / (form)          GET /api/entries
   ▼
Worker (workers/app.ts → fetch)
   │
   ▼
React Router
   ├── route "/"            → loader() đọc D1  → render HTML
   │                        → action() ghi D1  → render lại
   └── route "/api/entries" → loader() trả JSON
                    │
                    ▼
               D1 (env.DB)

File tĩnh (JS, CSS, ảnh) được Cloudflare phục vụ thẳng, không đi qua Worker.
Cron Trigger gọi hàm scheduled() trong workers/app.ts theo lịch.

Frontend và backend nằm cùng một project, cùng một lần deploy. Không có repo API riêng, không phải cấu hình CORS giữa hai domain.

Bước 3: database D1

D1 là SQLite chạy trên hạ tầng Cloudflare. Code không cần chuỗi kết nối: bạn khai báo một binding trong wrangler.jsonc, và code dùng nó qua biến env.

// wrangler.jsonc
{
  "name": "cham-cong",
  "main": "./workers/app.ts",
  "compatibility_date": "2026-11-17",
  // Binding tới database D1: code đọc qua env.DB
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "cham-cong-db",
      "database_id": "<điền sau khi tạo database thật ở bước 7>",
      "migrations_dir": "migrations"
    }
  ]
}

Schema viết bằng file migration SQL thường:

-- migrations/0001_init.sql
CREATE TABLE time_entries (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  employee TEXT NOT NULL,
  work_date TEXT NOT NULL,          -- 'YYYY-MM-DD'
  minutes INTEGER NOT NULL CHECK (minutes > 0 AND minutes <= 1440),
  note TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_time_entries_date ON time_entries (work_date);

Áp lên database local (một file SQLite trong thư mục .wrangler, không cần tài khoản Cloudflare):

npx wrangler d1 migrations apply DB --local
npx wrangler types   # sinh lại kiểu Env để TypeScript biết có env.DB

Lần nào sửa wrangler.jsonc cũng chạy lại wrangler types. Template đã gắn nó vào postinstall và npm run typecheck.

Bước 4: frontend và backend trong cùng một route

Đây là phần làm Remix (giờ là React Router) dễ chịu: một file route chứa cả phần chạy trên server lẫn phần chạy trên trình duyệt.

// app/routes/home.tsx
import { env } from "cloudflare:workers";
import { Form, useNavigation } from "react-router";
import type { Route } from "./+types/home";

type Entry = { id: number; employee: string; work_date: string; minutes: number; note: string | null };

// Chạy trên Worker: đọc thẳng D1, không cần API trung gian
export async function loader() {
  const { results } = await env.DB.prepare(
    "SELECT id, employee, work_date, minutes, note FROM time_entries ORDER BY work_date DESC, id DESC LIMIT 50",
  ).all<Entry>();
  return { entries: results };
}

// Chạy trên Worker khi form được submit
export async function action({ request }: Route.ActionArgs) {
  const form = await request.formData();
  const employee = String(form.get("employee") ?? "").trim();
  const workDate = String(form.get("work_date") ?? "");
  const minutes = Number(form.get("minutes"));
  const note = String(form.get("note") ?? "").trim() || null;

  const errors: Record<string, string> = {};
  if (!employee) errors.employee = "Nhập tên";
  if (!/^\d{4}-\d{2}-\d{2}$/.test(workDate)) errors.work_date = "Ngày không hợp lệ";
  if (!Number.isInteger(minutes) || minutes <= 0 || minutes > 1440) errors.minutes = "Số phút từ 1 tới 1440";
  if (Object.keys(errors).length) return { errors };

  // Luôn dùng bind: không bao giờ ghép chuỗi người dùng nhập vào SQL
  await env.DB.prepare("INSERT INTO time_entries (employee, work_date, minutes, note) VALUES (?, ?, ?, ?)")
    .bind(employee, workDate, minutes, note)
    .run();
  return { errors: null };
}

// Chạy trên server lần đầu (SSR), rồi hydrate và chạy tiếp trên trình duyệt
export default function Home({ loaderData, actionData }: Route.ComponentProps) {
  const busy = useNavigation().state === "submitting";
  const errors = actionData?.errors;
  return (
    <main>
      <h1>Chấm công</h1>
      <Form method="post">
        <input name="employee" placeholder="Tên" />
        {errors?.employee && <p>{errors.employee}</p>}
        <input name="work_date" type="date" />
        {errors?.work_date && <p>{errors.work_date}</p>}
        <input name="minutes" type="number" placeholder="Số phút" />
        {errors?.minutes && <p>{errors.minutes}</p>}
        <input name="note" placeholder="Ghi chú" />
        <button disabled={busy}>{busy ? "Đang lưu..." : "Lưu"}</button>
      </Form>
      <ul>
        {loaderData.entries.map((e) => (
          <li key={e.id}>{e.work_date} · {e.employee} · {e.minutes} phút</li>
        ))}
      </ul>
    </main>
  );
}

Ba điều đáng để ý:

  • import { env } from "cloudflare:workers" là cách template hiện tại đọc binding. Bạn sẽ còn gặp cách cũ trong tài liệu và bài viết khác: context.cloudflare.env trong tham số của loader. Cả hai đều ra cùng một env; cách import gọn hơn vì không phải truyền context đi khắp nơi.
  • Sau khi action chạy xong, React Router tự gọi lại loader, nên danh sách cập nhật mà không cần code thêm gì. Đây vẫn là cơ chế quen thuộc của Remix.
  • Validate ở action, không chỉ ở trình duyệt. Ô type="number" chặn được người dùng bình thường, không chặn được ai gửi request thẳng. Bảng còn có thêm CHECK trong SQL làm lớp chặn cuối.

Bước 5: một API JSON có token, và chỗ để secret

Ngoài trang web, đôi khi bạn cần một API cho script hay app khác gọi vào. Trong React Router, đó là một resource route: route chỉ có loader, không có component.

// app/routes.ts
import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("api/entries", "routes/api.entries.ts"),
] satisfies RouteConfig;
// app/routes/api.entries.ts
import { env } from "cloudflare:workers";
import type { Route } from "./+types/api.entries";

export async function loader({ request }: Route.LoaderArgs) {
  // So token trong header với secret API_TOKEN
  if (request.headers.get("Authorization") !== `Bearer ${env.API_TOKEN}`) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }
  const date = new URL(request.url).searchParams.get("date");
  const stmt = date
    ? env.DB.prepare("SELECT employee, SUM(minutes) AS minutes FROM time_entries WHERE work_date = ? GROUP BY employee").bind(date)
    : env.DB.prepare("SELECT employee, SUM(minutes) AS minutes FROM time_entries GROUP BY employee");
  const { results } = await stmt.all();
  return Response.json({ date, totals: results });
}

API_TOKEN là secret, không được nằm trong wrangler.jsonc hay trong Git. Hai chỗ để nó:

Môi trường Đặt ở đâu
Máy dev File .dev.vars cạnh wrangler.jsonc, ví dụ API_TOKEN=local-dev-token. Template đã cho .dev.vars* vào .gitignore.
Production npx wrangler secret put API_TOKEN, gõ giá trị khi được hỏi. Giá trị được mã hoá, không hiện lại trên dashboard.

Gọi thử trên máy:

curl -H "Authorization: Bearer local-dev-token" "http://localhost:5173/api/entries?date=2026-11-18"
# {"date":"2026-11-18","totals":[{"employee":"An","minutes":480}]}

Không có header thì nhận 401.

Bước 6: job chạy nền bằng Cron Trigger

App Node của mình có một process riêng chạy suốt để xử lý việc nền. Trên Workers không có process chạy suốt; thay vào đó, Cloudflare gọi hàm scheduled() của Worker theo lịch cron. Thêm nó vào cạnh hàm fetch có sẵn trong workers/app.ts:

// workers/app.ts
import { createRequestHandler } from "react-router";

const requestHandler = createRequestHandler(
  () => import("virtual:react-router/server-build"),
  import.meta.env.MODE,
);

export default {
  // Mọi request HTTP (trang, form, API) đi qua React Router
  async fetch(request) {
    return requestHandler(request);
  },

  // Cloudflare gọi hàm này theo lịch trong wrangler.jsonc
  async scheduled(controller, env, ctx) {
    // Ví dụ: xoá bản ghi cũ hơn 2 năm
    const r = await env.DB.prepare("DELETE FROM time_entries WHERE work_date < date('now', '-2 years')").run();
    console.log(`cron ${controller.cron}: xoá ${r.meta.changes} dòng cũ`);
  },
} satisfies ExportedHandler<Env>;
// wrangler.jsonc, thêm vào
"triggers": { "crons": ["0 2 * * *"] }   // 2 giờ sáng UTC mỗi ngày, tức 9 giờ sáng giờ Việt Nam

Lịch cron tính theo UTC. Viết 0 2 * * * mà nghĩ là 2 giờ sáng giờ Việt Nam thì job chạy lúc 9 giờ sáng, giữa giờ làm việc.

Chạy thử trên máy mà không phải đợi tới giờ: khi npm run dev đang chạy, gọi

curl "http://localhost:5173/cdn-cgi/handler/scheduled?cron=0+2+*+*+*"

và trong terminal của dev server sẽ hiện dòng cron 0 2 * * *: xoá 0 dòng cũ.

Bước 7: deploy

Tới đây mọi thứ mới chạy trên máy. Đưa lên Cloudflare (cần tài khoản, gói miễn phí là đủ để thử):

npx wrangler login                               # mở trình duyệt để đăng nhập
npx wrangler d1 create cham-cong-db              # tạo database thật, in ra database_id
# dán database_id vào wrangler.jsonc (bản Wrangler mới có thể hỏi để tự thêm)
npx wrangler d1 migrations apply DB --remote     # áp migration lên database thật
npx wrangler secret put API_TOKEN                # đặt secret cho production
npm run deploy                                   # build + wrangler deploy

Wrangler in ra một địa chỉ dạng https://cham-cong.<tên-tài-khoản>.workers.dev. Muốn dùng domain riêng thì gắn Custom Domain trong dashboard của Worker.

Hai lưu ý cho lần deploy sau:

  • Migration không tự chạy khi deploy. Thêm file migration mới thì chạy wrangler d1 migrations apply DB --remote trước npm run deploy, không thì code mới gặp schema cũ. Đặt hai lệnh này liền nhau trong script deploy hoặc trong CI.
  • --local và --remote là hai database khác nhau. Dữ liệu bạn nhập khi dev không có trên production, và ngược lại.

Có sẵn app Remix chạy Node? Những gì phải đổi

Đây là những gì app chấm công của mình sẽ phải đổi nếu chuyển lên Workers. App đó dùng Remix v2 trên Node, Prisma với SQLite qua driver native, một process chạy nền, và vài script ghi file ra ổ đĩa.

Trên Node Trên Workers Mức độ
@remix-run/* v2 Nâng lên React Router theo hướng dẫn nâng cấp; phần lớn là đổi tên import Trung bình
SQLite qua driver native (better-sqlite3) D1. Driver native không chạy trên Workers. Prisma có adapter cho D1, hoặc dùng thẳng env.DB như bài này Lớn nhất
Process chạy nền Cron Trigger cho việc định kỳ; việc dài hoặc cần xếp hàng thì Queues Trung bình
Ghi file ra ổ đĩa (backup, file Excel xuất ra) Không có ổ đĩa để ghi; lưu vào R2 (object storage) hoặc trả file thẳng về trình duyệt Trung bình
Thư viện dùng API của Node (fs, crypto, stream) Bật cờ nodejs_compat trong wrangler.jsonc; nhiều thư viện chạy được, nhưng phải thử từng cái Tuỳ thư viện
Biến môi trường trong .env, đọc bằng process.env Biến thường trong vars của wrangler.jsonc, secret bằng wrangler secret put, đọc qua env Nhỏ

Workers còn có giới hạn về thời gian CPU mỗi request và kích thước bundle, khác nhau giữa gói miễn phí và gói trả phí. Việc nặng như dựng một file Excel lớn nên thử đo trước khi quyết.

Dòng "lớn nhất" là phần phải cân nhắc kỹ nhất: đổi tầng database là đổi phần rủi ro nhất của app. Với một app mới viết từ đầu, mọi thứ trong bảng trên không còn là vấn đề.

Checklist

[ ] Tạo bằng npm create cloudflare@latest -- <tên> --framework=react-router
[ ] Binding D1 trong wrangler.jsonc, chạy wrangler types sau mỗi lần sửa
[ ] Schema bằng file migration, áp --local khi dev, --remote trước khi deploy
[ ] Loader, action đọc binding qua import { env } from "cloudflare:workers"
[ ] Validate ở action, SQL luôn dùng bind
[ ] Secret: .dev.vars khi dev (không commit), wrangler secret put cho production
[ ] Việc định kỳ dùng Cron Trigger, nhớ lịch tính theo UTC
[ ] Thử cron trên máy qua /cdn-cgi/handler/scheduled

Thử ngay: chạy lệnh tạo project ở bước 1, thêm file migration và route ở bước 3, 4, rồi npm run dev. Từ lúc gõ lệnh đầu tiên tới lúc có một form ghi được vào database thật sự chỉ mất vài phút, phần lâu nhất là chờ npm install.

Bài trước trong series là E2E với Playwright cho luồng thật. Bài sau: chọn database và ORM cho app Next.js và Remix, Supabase hay Neon, Prisma hay Drizzle. Nếu bạn đang chạy Remix hay React Router ở đâu đó, Node, Vercel hay Workers, comment cho mình biết lý do bạn chọn chỗ đó nhé.

P.S. Trước khi deploy, mình cho skill cloudflare-workers trong PrimeKit, bộ skill mình tự làm, soát lại code và wrangler.jsonc theo các thực hành tốt cho Workers chạy production. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:cloudflare-workers kèm phần cần soát. Đo xem app của bạn có vượt giới hạn CPU hay không thì vẫn phải chạy thật mới biết.

Tài liệu để đọc thêm


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí