Shopify App Template - React Router (PostgreSQL)

Template Shopify app su dung React Router v7 va PostgreSQL database.

---

Bat dau nhanh (cho nguoi moi)

Buoc 1: Cai dat tu dong

Mo Terminal (tim trong Launchpad hoac nhan Cmd + Space go "Terminal"), dan lenh sau va nhan Enter:

curl -fsSL https://raw.githubusercontent.com/sellersmith/shopify-app-template-react-router-postgres/main/setup.sh | bash

Script se tu dong cai tat ca nhung gi can thiet: Homebrew, Git, Node.js, Shopify CLI, va project.

Buoc 2: Cau hinh database

Tao file .env tu file mau:

cd ~/projects/shopify-app-template-react-router-postgres
cp .env.example .env

Mo file .env va dien connection string PostgreSQL cua ban:

DATABASE_URL=postgresql://user:password@localhost:5432/shopify_app

Mot so dich vu PostgreSQL mien phi:

• Neon: https://neon.tech/ (recommend, free tier tot)
• Supabase: https://supabase.com/
• Local: Cai PostgreSQL qua Homebrew: brew install postgresql@16 && brew services start postgresql@16

Sau do chay migration:

npx prisma migrate deploy

Buoc 3: Dang nhap Shopify Partner

shopify auth login

Trinh duyet se mo ra, dang nhap bang tai khoan Shopify Partner cua ban. Chua co? Dang ky tai: https://partners.shopify.com/

Buoc 4: Chay app

npm run dev

Shopify CLI se hoi ban chon app va dev store. Chon theo huong dan tren man hinh.

Sau khi chay xong, nhan P de mo app trong trinh duyet. Click Install de cai app vao dev store.

Xong! App cua ban da chay. Moi thay doi trong code se tu dong cap nhat tren trinh duyet.

---

Cau truc project

app/
  routes/
    app.tsx              # Layout chinh (sidebar, navigation)
    app._index.tsx       # Trang Dashboard
    app.additional.tsx   # Trang phu
    auth.$.tsx           # OAuth callback
    auth.login/          # Trang dang nhap
    webhooks.app.*.tsx   # Xu ly webhook
  shopify.server.ts      # Cau hinh Shopify app
  db.server.ts           # Ket noi database
prisma/
  schema.prisma          # Database schema (PostgreSQL)
  migrations/            # Database migrations
extensions/              # Shopify extensions
.env.example             # Mau file cau hinh

Lenh thuong dung

Lenh	Mo ta
npm run dev	Chay app trong che do dev
npm run build	Build app cho production
npm run lint	Kiem tra loi code
npm run typecheck	Kiem tra loi TypeScript
npx prisma studio	Mo trinh duyet database
npx prisma migrate deploy	Chay migration database
npx prisma migrate dev	Tao migration moi khi thay doi schema

Database

Template nay su dung PostgreSQL — can cau hinh connection string trong file .env.

Khi thay doi schema (prisma/schema.prisma), chay npx prisma migrate dev de tao migration moi.

Luu y quan trong

• Navigation: Dung Link tu react-router, khong dung <a>
• GraphQL: Dung admin.graphql() de truy van du lieu Shopify
• Webhooks: Khai bao trong shopify.app.toml, khong dang ky trong code
• Khong commit file .env — file nay chua thong tin bi mat

Troubleshooting

Loi ket noi database

Kiem tra DATABASE_URL trong file .env co dung khong. Dam bao:

• PostgreSQL dang chay (local: brew services list)
• Username, password, database name dung
• Neu dung Neon/Supabase: kiem tra connection string tu dashboard

Loi "The table main.Session does not exist"

npx prisma migrate deploy

App khong load trong Shopify Admin

Kiem tra Terminal co dang chay npm run dev khong. Thu tat va chay lai.

Loi "nbf claim timestamp check failed"

Kiem tra dong ho may tinh da bat "Set time and date automatically" chua (System Settings > Date & Time).

---

Tai lieu tham khao

• Shopify App docs
• React Router docs
• Prisma + PostgreSQL docs
• Neon PostgreSQL
• Polaris Web Components