Hướng dẫn cài đặt môi trường cho dự án React JS hiện đại

React hiện không còn khuyến nghị Create React App cho dự án mới. Tài liệu chính thức ưu tiên framework cho ứng dụng production; khi cần SPA client-only hoặc học React từ nền tảng, Vite là lựa chọn gọn để dựng môi trường.

Chọn framework hay Vite

Cài Node.js LTS

Dùng nvm, fnm hoặc Volta để quản lý phiên bản. Sau khi cài:

node --version
npm --version
git --version

Nên commit file lock và dùng cùng package manager trong cả nhóm. Có thể thêm .nvmrc hoặc trường engines để ghi rõ phiên bản.

Tạo dự án React với Vite

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install
npm run dev

Template react-ts dùng TypeScript; đổi thành react nếu dự án chọn JavaScript. Terminal sẽ in URL local, thường là http://localhost:5173.

Hiểu cấu trúc tối thiểu

• src/main.tsx: tạo React root và mount ứng dụng.
• src/App.tsx: component gốc mẫu.
• public/: tài sản được phục vụ nguyên trạng.
• vite.config.ts: plugin, alias, proxy và build configuration.
• package.json: scripts và dependency.

Biến môi trường

Vite chỉ đưa biến có tiền tố VITE_ vào mã client:

# .env.example
VITE_API_URL=https://api.example.test

// src/config.ts
export const apiUrl = import.meta.env.VITE_API_URL;

Mọi biến được đưa vào bundle frontend đều có thể bị người dùng đọc. Không lưu private key, mật khẩu database hoặc secret backend trong VITE_*.

Thiết lập chất lượng mã

Giữ ESLint đi kèm template và bổ sung formatter theo convention của nhóm. Các lệnh tối thiểu nên chạy được trong CI:

npm run lint
npm run build
npm run preview

preview chỉ dùng để kiểm tra build local, không phải production server.

Proxy API khi phát triển

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': 'http://localhost:8000',
    },
  },
});

Proxy giúp tránh cấu hình CORS phức tạp ở local, nhưng production vẫn cần domain, reverse proxy và chính sách CORS đúng.

Cài công cụ trình duyệt

React Developer Tools hỗ trợ xem component tree, props, state và profiling. Bên cạnh đó, dùng tab Network và Performance của trình duyệt để kiểm tra request, bundle và render.

Lỗi thường gặp

• Unsupported engine: Node không đúng phiên bản; chuyển phiên bản bằng trình quản lý rồi cài lại dependency.
• Port đã dùng: Vite chọn cổng khác hoặc truyền --port.
• Biến môi trường undefined: kiểm tra tiền tố VITE_ và khởi động lại dev server.
• Trang trắng khi deploy subfolder: cấu hình base và route fallback phù hợp.
• Module resolution lỗi: tránh trộn nhiều lock file và xóa node_modules chỉ sau khi hiểu nguyên nhân.

Checklist trước khi bắt đầu code

1. Nhóm đã chọn framework hay SPA client-only dựa trên yêu cầu thật.
2. Node và package manager được ghi phiên bản.
3. Lock file được commit.
4. Lint và production build chạy thành công.
5. .env.example không chứa secret.
6. README ghi lệnh cài, chạy, test và build.

Nguồn tham khảo

• React Installation
• Build a React app from scratch
• Vite Guide