Hướng dẫn cài đặt template Next.js 16 / React 19 từ K-Source

Bạn vừa mua một template Next.js 16 và React 19 từ K-Source và muốn biết cách cài đặt và chạy nó? Bài viết này sẽ hướng dẫn bạn từng bước từ chuẩn bị môi trường đến vận hành ứng dụng.

Chuẩn bị môi trường Node.js

Trước tiên, bạn cần đảm bảo hệ thống của mình có phiên bản Node.js phù hợp. Yêu cầu tối thiểu là Node.js 18.17, nhưng khuyến khích dùng phiên bản 20 LTS để đảm bảo hiệu suất.

• Kiểm tra phiên bản Node.js hiện tại bằng lệnh:

node -v

• Nếu cần cập nhật, bạn có thể tải phiên bản mới nhất từ trang chủ Node.js hoặc sử dụng nvm (Node Version Manager) để quản lý phiên bản.

Giải nén gói zip

Sau khi tải về gói zip từ K-Source, bạn cần giải nén để sử dụng hai thư mục: nextjs và reactjs. Mỗi thư mục chứa mã nguồn độc lập cho ứng dụng Next.js và React.

• Thư mục nextjs: Sử dụng Next.js 16 với TypeScript, Bootstrap 5 + SCSS.
• Thư mục reactjs: Sử dụng React 19 và Vite 7.

Cấu hình tệp .env

Sau khi giải nén, bạn cần cấu hình các biến môi trường cho mỗi dự án. Thực hiện các bước sau:

1. Di chuyển vào thư mục cần cấu hình, ví dụ nextjs.
2. Sao chép tệp mẫu .env.example thành .env.local bằng lệnh:

cp .env.example .env.local

Kiểm tra và điều chỉnh các biến môi trường theo nhu cầu của bạn.

Cài đặt gói npm

Tiếp theo, thực hiện cài đặt các gói cần thiết cho dự án bằng cách chạy lệnh sau trong thư mục dự án:

npm install

Lệnh này sẽ tải về và cài đặt tất cả các thư viện và phụ thuộc cần thiết cho ứng dụng.

Chạy ứng dụng ở chế độ phát triển

Sau khi cài đặt xong, bạn có thể chạy ứng dụng ở chế độ phát triển:

• Đối với nextjs:

npm run dev

• Đối với reactjs:

npm run dev

Ứng dụng sẽ chạy trên cổng 3000 cho Next.js và cổng 5173 cho React.

Build và chạy ứng dụng ở chế độ production

Khi đã sẵn sàng, bạn có thể build ứng dụng để chạy ở chế độ production:

• Build dự án:

npm run build

• Chạy ứng dụng:

npm run start

Sử dụng Docker Compose

Nếu bạn muốn chạy ứng dụng qua Docker Compose, hãy thực hiện các bước sau:

1. Đảm bảo Docker đã được cài đặt trên máy.
2. Chạy lệnh sau trong thư mục dự án:

docker compose up -d

Lệnh này sẽ khởi động ứng dụng trong môi trường Docker.

Lỗi thường gặp

• Node cũ: Kiểm tra và cập nhật Node.js nếu gặp lỗi phiên bản.
• Cổng bận: Thay đổi cổng hoặc dừng các ứng dụng đang chiếm cổng.
• Thiếu .env: Đảm bảo bạn đã sao chép và cấu hình đúng tệp .env.
• Lỗi sharp trên Windows: Cài đặt lại gói sharp hoặc xem hướng dẫn khắc phục trên K-Source FAQ.

Câu hỏi thường gặp

Làm thế nào để kiểm tra phiên bản Node.js?

Sử dụng lệnh node -v trong terminal.

Tại sao ứng dụng không chạy được trên cổng 3000?

Có thể cổng 3000 đang được sử dụng. Thử dừng ứng dụng khác hoặc thay đổi cổng.

Làm sao để cập nhật các gói npm?

Chạy npm update trong thư mục dự án.

Khi đã hoàn tất cài đặt, bạn có thể xem thêm các mẫu template có sẵn khác để mở rộng dự án của mình.