Chuyển tới nội dung chính

ZaUI Coffee

ZaUI Coffee là một dự án mã nguồn mở cung cấp bộ giao diện mẫu (UI Template) cho các ứng dụng thuộc lĩnh vực Dịch vụ ăn uống (FnB), Kinh doanh Cửa hàng Cà phê hoặc Nhà hàng trên nền tảng Zalo Mini App.

Dự án này giúp các lập trình viên khởi tạo dự án nhanh chóng, tái sử dụng các component giao diện chuẩn mực và tập trung vào việc phát triển logic nghiệp vụ.

Demo

Demo

Figma

QR Code

Demo

Tính năng chính​

Bộ template bao gồm các tính năng thiết yếu:

  • Xem thông tin & Menu: Xem chi tiết về cửa hàng cà phê và danh sách menu thực đơn.
  • Đặt hàng & Tùy chọn: Đặt cà phê và đồ ăn nhẹ với các tùy chọn tùy chỉnh kích cỡ (size).
  • Quản lý thông báo: Quản lý các thông báo (notifications) nhận được.
  • Giỏ hàng & Giao hàng: Quản lý giỏ hàng và các tùy chọn giao hàng (delivery options).
  • Tài khoản & Thành viên: Xem hồ sơ khách hàng và thông tin thành viên (membership).

Tech stack​

reactzmp-uizmp-sdkrecoiltailwindcssscss

Dự án được xây dựng dựa trên các thư viện và công cụ:

  • Core: React, Zalo Mini App SDK (zmp-sdk), Zalo Mini App UI Kit (zmp-ui).
  • State Management: Recoil.
  • Styling: TailwindCSS, SCSS (Sass).
  • Build Tool: Vite.

Hướng dẫn cài đặt và sử dụng​

Sử dụng Zalo Mini App Extension​

  1. Cài đặt Visual Studio Code và Zalo Mini App Extension.
  2. Nhấp vào Create Project > Chọn template ZaUI Coffee > Đợi cho đến khi dự án được khởi tạo xong.
  3. Cấu hình App ID và Cài đặt các thư viện (Dependencies), sau đó chuyển đến bảng Run > chọn Start để bắt đầu phát triển Mini App của bạn 🚀

Sử dụng Zalo Mini App CLI​

  1. Cài đặt Node JS
  2. Cài đặt Mini App DevTools CLI
  3. Tải xuống hoặc clone repository này
  4. Cài đặt các thư viện bổ trợ:
  npm install
  1. Khởi chạy server phát triển bằng zmp-cli:
  zmp start
  1. Mở localhost:3000 trên trình duyệt và bắt đầu lập trình 🔥

Triển khai (Deployment)​

  1. Tạo một mini app. Để xem hướng dẫn cách tạo mini app, vui lòng tham khảo Coffee Shop Tutorial
  2. Thiết lập phương thức thanh toán nếu bạn muốn chấp nhận thanh toán trực tuyến.
  3. Triển khai mini app của bạn lên Zalo bằng Mini App ID đã tạo ở bước 1.

Nếu đang dùng zmp-cli:

  zmp login
  zmp deploy
  1. Quét mã QR bằng ứng dụng Zalo để xem trước (preview) mini app của bạn.

Cấu trúc & Tùy biến (Usage):​

Repository này chứa các component UI mẫu để xây dựng ứng dụng của bạn. Bạn có thể tích hợp các API nội bộ để lấy dữ liệu nhà hàng, thực đơn, lịch sử đặt chỗ, hoặc chỉnh sửa mã nguồn để phù hợp với nhu cầu kinh doanh.

Cấu trúc thư mục

  • src: Chứa toàn bộ mã nguồn logic của Mini App. Bên trong thư mục src gồm:
    • components: Các component có thể tái sử dụng, được viết bằng React.JS.
    • css: Các tệp stylesheet; hỗ trợ cả pre-processor.
    • pages: Mỗi Page cũng là một component nhưng đóng vai trò như một màn hình hoàn chỉnh và phải được đăng ký trong app.tsx dưới dạng một Route.
    • statics: Các tệp SVG và hình ảnh được import trực tiếp vào bundle mã nguồn.
    • types: Chứa các khai báo kiểu và interface của TypeScript.
    • utils: Các hàm tiện ích dùng chung, ví dụ: tính khoảng cách, định dạng ngày giờ, v.v.
    • app.ts: Điểm khởi đầu (entry point) của Mini App.
    • global.d.ts: Chứa các khai báo TypeScript cho module bên thứ ba và các đối tượng global.
    • state.ts: Quản lý state, bao gồm các atom và selector của Recoil.
    • mock: Dữ liệu mẫu dưới dạng các tệp *.json.
  • app-config.json: Cấu hình toàn cục cho Mini App.

Các tệp còn lại (như tailwind.config.js, vite.config.ts, tsconfig.json, postcss.config.js) là các tệp cấu hình cho những thư viện được sử dụng trong ứng dụng. Hãy tham khảo tài liệu của từng thư viện để biết cách sử dụng chi tiết.

Tích hợp (Recipes)​

Thay đổi tên cửa hàng​

Chỉ cần thay đổi thuộc tính app.title trong app-config.json:

{
  "app": {
    "title": "ZaUI Coffee"
  }
}

Tải danh sách sản phẩm từ server​

Với một MVP đơn giản, bạn có thể khai báo sản phẩm và danh mục cửa hàng bằng cách chỉnh sửa các tệp mock/\*.json. Tuy nhiên, với một ứng dụng thực tế, bạn thường sẽ cần lấy dữ liệu thông qua REST API.

Để thực hiện HTTP GET request đến server và lấy danh sách sản phẩm, hãy cập nhật selector productsState trong src/state.ts để sử dụng fetch.

Nếu cấu trúc JSON trả về khác với template hiện có, bạn cần map dữ liệu sản phẩm của mình sang interface Product tương ứng. Ví dụ:

export const productsState = selector<Product[]>({
  key: "products",
  get: async () => {
    const response = await fetch(
      "[https://dummyjson.com/products](https://dummyjson.com/products)",
    );
    const data = await response.json();
    return data.products.map(
      ({ id, title, price, images, description, category }) =>
        <Product>{
          id,
          name: title,
          price: price,
          image: images[0],
          description,
          categoryId: category,
        },
    );
  },
});
Products fetching

Design Disclaimer​

Lưu ý:

  • Nội dung thiết kế, hình ảnh minh họa và ví dụ trong bài viết này chỉ mang tính chất tham khảo nhằm phục vụ mục đích nghiên cứu, minh họa và thử nghiệm.

  • Zalo Group không chịu trách nhiệm cho bất kỳ việc sử dụng, triển khai hoặc diễn giải nào phát sinh từ nội dung này trong môi trường thực tế hoặc thương mại.

License​

Copyright (c) Zalo Group. and its affiliates. All rights reserved.

The examples provided by Zalo Group are for non-commercial testing and evaluation purposes only. Zalo Group reserves all rights not expressly granted.

ZaUI Coffee

zi-chevron-up
miniapp-logo

Khám phá