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.envtrong tham số của loader. Cả hai đều ra cùng mộtenv; cách import gọn hơn vì không phải truyềncontextđ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êmCHECKtrong 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 --remotetrướcnpm 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. --localvà--remotelà 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
- React Router (formerly Remix) trên Workers, Cloudflare Docs
- Nâng cấp từ Remix lên React Router
- Bắt đầu với D1 và D1 migrations
- Cron Triggers
- Secrets
- Bindings
Series khác của mình
- SQL thực chiến: Những bài học mình ước đã biết sớm hơn: viết query dễ đọc, đọc execution plan, lỗi NULL và N+1 không báo lỗi, schema và transaction, phân trang bằng con trỏ.
- Backend .NET thực chiến: những case hay gặp trên production: async/await làm treo API, HttpClient hết socket, EF Core kéo cả bảng, idempotency, outbox, caching, bảo mật API.
- DevOps thực chiến: Docker, Portainer và Azure Pipelines từ máy dev lên server: Dockerfile, Compose cho dev và prod, secret trong container, Portainer, pipeline Azure, deploy có rollback.
- Dùng AI hiệu quả trong công việc: kinh nghiệm thực chiến của dev: viết prompt đủ ngữ cảnh, bắt AI bịa API, giao việc cho agent, review code AI viết, debug, đọc codebase lạ, đóng gói quy trình thành skill.
All rights reserved