Workspace Architecture

Structure workspace với apps, libs, và thin apps.

Library Types và Organization

Tổ chức libraries theo type: feature, data-access, ui, util.

Feature Module Pattern

Sử dụng feature module pattern để tổ chức theo domain.

Module Boundaries và Dependencies

Enforce module boundaries với NX dependency rules.

Build và Development Workflow

Tối ưu builds với caching và affected commands.

Tổng kết & Tiếp theo

Tóm tắt và preview phần tiếp theo của series.

Vietnamese Flag

Name: Giới thiệu về kiến trúc dự án NX
Author: Nguyễn Phi Vũ

Giới thiệu về kiến trúc dự án NX

Nguyễn Phi VũSoftware Engineer, NAB

Đây là phần trong series của mình về modern tooling cho indie full-stack developers. Mình xây dựng các side projects để tiếp tục trau dồi kỹ năng trong thời đại AI—và mình muốn chia sẻ những gì đã học để tất cả chúng ta có thể tiếp tục build những thứ thú vị cùng nhau.

Trong bài hướng dẫn này, chúng ta sẽ khám phá NX monorepos—một tool rất mạnh để giúp structure codebase cho việc scale, maintain, và build development workflow hiệu quả.

Yêu cầu

Hiểu biết cơ bản về JavaScript/TypeScript
Quen thuộc với package managers như npm, yarn, pnpm, v.v.
Một số kinh nghiệm với JavaScript frontend và backend frameworks (ví dụ: React, Node.js)

monorepo/

├── apps/ # Thin, deployable entry points

│ ├── web-app/ # Main Web App

│ ├── mobile-app/ # Main Mobile app

│ ├── api-server/ # Nodejs Backend API

│ └── admin-dashboard/ # Admin App

│

├── libs/ # Where the actual code lives

│ ├── web-modules/ # App-specific feature modules

│ │ └── src/

│ │ ├── feature-auth/

│ │ ├── feature-dashboard/

│ │ └── feature-settings/

│ ├── ui/ # Shared UI components

│ │ └── src/

│ │ ├── button/

│ │ ├── card/

│ │ └── modal/

│ ├── shared/ # Shared types, utils, constants

│ │ └── src/

│ │ ├── types/

│ │ ├── utils/

│ │ └── constants/

│ └── db/ # Database layer

│ └── src/

│ ├── prisma/

│ └── queries/

│

├── tools/ # Custom scripts and generators

├── nx.json # NX workspace configuration

├── tsconfig.base.json # Path aliases configuration

└── package.json # Dependencies and scripts

Chào mừng bạn đến với Phần 1 của series NX Monorepo! Trong phần này, chúng ta sẽ tìm hiểu các concepts nền tảng và architecture patterns để xây dựng fullstack monorepos có khả năng scale. Phần 2 sẽ là walkthrough thực hành, nơi chúng ta xây dựng một repository hoàn chỉnh từ đầu.

Quyết Định Chiến Lược Repository

Khi quản lý nhiều projects liên quan, các team thường chọn giữa hai chiến lược:

Polyrepo (các repository riêng biệt): Mỗi project nằm trong repository riêng với versioning độc lập, CI/CD, và release cycles. Phù hợp cho người mới và team nhỏ khi mới bắt đầu.

Monorepo (một repository duy nhất): Tất cả các projects liên quan chia sẻ một repository, cho phép chia sẻ code và thay đổi atomic trên toàn bộ codebase.

Các công ty như Google, Meta, Microsoft, và nhiều công ty khác sử dụng monorepos để quản lý các codebases khổng lồ của họ. Nhưng monorepos không chỉ dành cho big tech—chúng ngày càng phổ biến với các team thuộc mọi quy mô.

Tại Sao Chọn Monorepo?

Khía Cạnh	Polyrepo	Monorepo
Chia Sẻ Code	Publish packages lên npm, quản lý versions	Import trực tiếp, luôn đồng bộ
Thay Đổi Cross-project	Nhiều PRs trên các repos	Một commit atomic duy nhất
Cập Nhật Dependencies	Cập nhật từng repo riêng	Một cập nhật, tất cả projects
Tooling & Config	Duplicate trên các repos	Chia sẻ, thiết lập nhất quán
Refactoring	Cần phối hợp phức tạp	IDE hỗ trợ, tức thì

Vấn Đề: Monorepos Thiếu Tooling Phù Hợp

Chỉ đơn giản gom tất cả code vào một repository (code collocation) là không đủ. Thiếu tooling phù hợp, monorepos trở nên khó quản lý:

Pain Points Thường Gặp Khi Dùng Monorepo

CI/CD Chậm: Mỗi thay đổi kích hoạt builds và tests cho TẤT CẢ projects, kể cả những cái không liên quan
Không có ranh giới: Bất kỳ code nào cũng có thể import bất kỳ code nào khác, dẫn đến dependencies rối rắm
Tooling không nhất quán: Mỗi project sử dụng commands và configurations khác nhau
Onboarding khó khăn: Developers mới gặp khó khăn trong việc hiểu các mối quan hệ project
Vấn đề scaling: Khi repo phát triển, mọi thứ trở nên chậm hơn

Đây là lý do tại sao nhiều team từ bỏ monorepos—không phải vì monorepos tệ, mà vì họ thiếu tooling phù hợp.

NX: Giúp Monorepos Scale Hiệu Quả

NX được tạo ra để giải quyết chính xác những vấn đề này. Nó biến một code collocation đơn giản thành một true monorepo với tooling thông minh:

Cách NX Giải Quyết Mỗi Thách Thức:

1. Task Caching — Không bao giờ rebuild code không thay đổi

NX cache output của mỗi task (build, test, lint)
Nếu inputs không thay đổi, NX restore từ cache ngay lập tức
Với NX Cloud, cache được chia sẻ trên toàn team và CI

2. Affected Commands — Chỉ chạy những gì cần thiết

NX phân tích các thay đổi code và dependency graph
Chỉ các projects bị ảnh hưởng được rebuild, test, hoặc lint
Một thay đổi nhỏ không kích hoạt rebuild toàn bộ repo

3. Module Boundaries — Thực thi các quy tắc kiến trúc

Định nghĩa projects nào có thể depend on projects nào
Các quy tắc ESLint ngăn chặn imports không được phép
Giữ kiến trúc sạch khi codebase phát triển

4. Dependency Graph — Hiểu codebase của bạn

Trực quan hóa các mối quan hệ project với nx graph
Hiểu tác động của các thay đổi trước khi thực hiện chúng
Xác định circular dependencies và các vấn đề kiến trúc

5. Consistent Tooling — Plugins và Generators

Các commands chuẩn hóa trên tất cả projects
Generators tạo projects mới với best practices tích hợp sẵn
Plugins cung cấp các tối ưu hóa cụ thể cho framework

Phần 1: Giới Thiệu về NX Monorepos

Giới thiệu về kiến trúc dự án NX

Nguyễn Phi VũSoftware Engineer, NAB

Yêu cầu

Hiểu biết cơ bản về JavaScript/TypeScript
Quen thuộc với package managers như npm, yarn, pnpm, v.v.
Một số kinh nghiệm với JavaScript frontend và backend frameworks (ví dụ: React, Node.js)

monorepo/

├── apps/ # Thin, deployable entry points

│ ├── web-app/ # Main Web App

│ ├── mobile-app/ # Main Mobile app

│ ├── api-server/ # Nodejs Backend API

│ └── admin-dashboard/ # Admin App

│

├── libs/ # Where the actual code lives

│ ├── web-modules/ # App-specific feature modules

│ │ └── src/

│ │ ├── feature-auth/

│ │ ├── feature-dashboard/

│ │ └── feature-settings/

│ ├── ui/ # Shared UI components

│ │ └── src/

│ │ ├── button/

│ │ ├── card/

│ │ └── modal/

│ ├── shared/ # Shared types, utils, constants

│ │ └── src/

│ │ ├── types/

│ │ ├── utils/

│ │ └── constants/

│ └── db/ # Database layer

│ └── src/

│ ├── prisma/

│ └── queries/

│

├── tools/ # Custom scripts and generators

├── nx.json # NX workspace configuration

├── tsconfig.base.json # Path aliases configuration

└── package.json # Dependencies and scripts

Quyết Định Chiến Lược Repository

Khi quản lý nhiều projects liên quan, các team thường chọn giữa hai chiến lược:

Monorepo (một repository duy nhất): Tất cả các projects liên quan chia sẻ một repository, cho phép chia sẻ code và thay đổi atomic trên toàn bộ codebase.

Tại Sao Chọn Monorepo?

Khía Cạnh	Polyrepo	Monorepo
Chia Sẻ Code	Publish packages lên npm, quản lý versions	Import trực tiếp, luôn đồng bộ
Thay Đổi Cross-project	Nhiều PRs trên các repos	Một commit atomic duy nhất
Cập Nhật Dependencies	Cập nhật từng repo riêng	Một cập nhật, tất cả projects
Tooling & Config	Duplicate trên các repos	Chia sẻ, thiết lập nhất quán
Refactoring	Cần phối hợp phức tạp	IDE hỗ trợ, tức thì

Vấn Đề: Monorepos Thiếu Tooling Phù Hợp

Chỉ đơn giản gom tất cả code vào một repository (code collocation) là không đủ. Thiếu tooling phù hợp, monorepos trở nên khó quản lý:

Pain Points Thường Gặp Khi Dùng Monorepo

CI/CD Chậm: Mỗi thay đổi kích hoạt builds và tests cho TẤT CẢ projects, kể cả những cái không liên quan
Không có ranh giới: Bất kỳ code nào cũng có thể import bất kỳ code nào khác, dẫn đến dependencies rối rắm
Tooling không nhất quán: Mỗi project sử dụng commands và configurations khác nhau
Onboarding khó khăn: Developers mới gặp khó khăn trong việc hiểu các mối quan hệ project
Vấn đề scaling: Khi repo phát triển, mọi thứ trở nên chậm hơn

Đây là lý do tại sao nhiều team từ bỏ monorepos—không phải vì monorepos tệ, mà vì họ thiếu tooling phù hợp.

NX: Giúp Monorepos Scale Hiệu Quả

NX được tạo ra để giải quyết chính xác những vấn đề này. Nó biến một code collocation đơn giản thành một true monorepo với tooling thông minh:

Cách NX Giải Quyết Mỗi Thách Thức:

1. Task Caching — Không bao giờ rebuild code không thay đổi

NX cache output của mỗi task (build, test, lint)
Nếu inputs không thay đổi, NX restore từ cache ngay lập tức
Với NX Cloud, cache được chia sẻ trên toàn team và CI

2. Affected Commands — Chỉ chạy những gì cần thiết

NX phân tích các thay đổi code và dependency graph
Chỉ các projects bị ảnh hưởng được rebuild, test, hoặc lint
Một thay đổi nhỏ không kích hoạt rebuild toàn bộ repo

3. Module Boundaries — Thực thi các quy tắc kiến trúc

Định nghĩa projects nào có thể depend on projects nào
Các quy tắc ESLint ngăn chặn imports không được phép
Giữ kiến trúc sạch khi codebase phát triển

4. Dependency Graph — Hiểu codebase của bạn

Trực quan hóa các mối quan hệ project với nx graph
Hiểu tác động của các thay đổi trước khi thực hiện chúng
Xác định circular dependencies và các vấn đề kiến trúc

5. Consistent Tooling — Plugins và Generators

Các commands chuẩn hóa trên tất cả projects
Generators tạo projects mới với best practices tích hợp sẵn
Plugins cung cấp các tối ưu hóa cụ thể cho framework

Phần 1: Giới Thiệu về NX Monorepos

Giới thiệu về kiến trúc dự án NX

Phần 1: Giới Thiệu về NX Monorepos

Phần 2: Kiến Trúc Workspace

Phần 3: Các Loại Library và Tổ Chức

Phần 4: Feature Module Pattern

Phần 5: Module Boundaries và Dependencies

Phần 6: Build và Development Workflow

Phần 7: Tổng Kết & Tiếp Theo

Nguyễn Phi Vũ

Giới thiệu về kiến trúc dự án NX

Phần 1: Giới Thiệu về NX Monorepos

Phần 2: Kiến Trúc Workspace

Phần 3: Các Loại Library và Tổ Chức

Phần 4: Feature Module Pattern

Phần 5: Module Boundaries và Dependencies

Phần 6: Build và Development Workflow

Phần 7: Tổng Kết & Tiếp Theo

Nguyễn Phi Vũ