21 tháng 7, 2025Tiếng Việt

Làm chủ cấu hình TypeScript với hướng dẫn chuyên sâu về tsconfig.json. Tìm hiểu các tùy chọn trình biên dịch thiết yếu, thiết lập dự án và các cấu hình nâng cao để phát triển hiệu quả.

Cấu hình TypeScript: Hướng dẫn Toàn diện về tsconfig.json

TypeScript, một tập hợp con mở rộng của JavaScript, mang đến kiểu tĩnh cho thế giới năng động của phát triển web. Một tệp tsconfig.json được cấu hình tốt là rất quan trọng để khai thác toàn bộ sức mạnh của TypeScript. Hướng dẫn này cung cấp một cái nhìn tổng quan toàn diện về tsconfig.json, bao gồm các tùy chọn trình biên dịch thiết yếu, thiết lập dự án và các cấu hình nâng cao.

tsconfig.json là gì?

Tệp tsconfig.json là một tệp cấu hình chỉ định các tùy chọn trình biên dịch cho một dự án TypeScript. Nó cho trình biên dịch TypeScript biết cách chuyển mã TypeScript thành JavaScript. Tệp này rất cần thiết để xác định cấu trúc của dự án, thiết lập các quy tắc biên dịch và đảm bảo tính nhất quán trong đội ngũ phát triển, cho dù đội ngũ đó làm việc tại một văn phòng duy nhất hay phân tán trên nhiều châu lục.

Tạo tệp tsconfig.json

Để tạo tệp tsconfig.json, hãy điều hướng đến thư mục gốc của dự án trong terminal và chạy lệnh sau:

            tsc --init

Lệnh này tạo ra một tệp tsconfig.json cơ bản với các tùy chọn trình biên dịch thường được sử dụng. Sau đó, bạn có thể tùy chỉnh tệp để phù hợp với các yêu cầu cụ thể của dự án. Một tệp tsconfig.json điển hình sẽ bao gồm các tùy chọn như compilerOptions, include, và exclude.

Các Tùy chọn Trình biên dịch Thiết yếu

Phần compilerOptions là trái tim của tệp tsconfig.json. Nó chứa một loạt các tùy chọn kiểm soát hành vi của trình biên dịch TypeScript. Dưới đây là một số tùy chọn trình biên dịch quan trọng nhất:

`target`

Tùy chọn target chỉ định phiên bản mục tiêu ECMAScript cho mã JavaScript được tạo ra. Các giá trị phổ biến bao gồm ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Việc chọn đúng target là rất quan trọng để đảm bảo tính tương thích với môi trường chạy dự kiến, chẳng hạn như các phiên bản trình duyệt hoặc Node.js.

Ví dụ:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}

`module`

Tùy chọn module chỉ định kiểu tạo mã mô-đun. Các giá trị phổ biến bao gồm CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020, và ESNext. Việc lựa chọn hệ thống mô-đun phụ thuộc vào môi trường mục tiêu và công cụ đóng gói mô-đun được sử dụng (ví dụ: Webpack, Rollup, Parcel). Đối với Node.js, CommonJS thường được sử dụng, trong khi đối với các ứng dụng web hiện đại, ES6 hoặc ESNext với một công cụ đóng gói mô-đun được ưu tiên. Sử dụng ESNext cho phép các nhà phát triển tận dụng các tính năng và tối ưu hóa mới nhất, trong khi dựa vào công cụ đóng gói để xử lý định dạng mô-đun cuối cùng.

Ví dụ:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}

`lib`

Tùy chọn lib chỉ định một danh sách các tệp thư viện sẽ được bao gồm trong quá trình biên dịch. Các tệp thư viện này cung cấp các định nghĩa kiểu cho các API JavaScript tích hợp sẵn và các API của trình duyệt. Các giá trị phổ biến bao gồm ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String, và nhiều hơn nữa. Việc chọn các thư viện phù hợp đảm bảo rằng trình biên dịch TypeScript có thông tin kiểu cần thiết cho môi trường mục tiêu. Sử dụng thư viện DOM cho phép dự án biên dịch mã sử dụng các API dành riêng cho trình duyệt mà không gặp lỗi kiểu.

Ví dụ:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

`allowJs`

Tùy chọn allowJs cho phép trình biên dịch TypeScript biên dịch các tệp JavaScript cùng với các tệp TypeScript. Điều này hữu ích cho việc di chuyển các dự án JavaScript hiện có sang TypeScript một cách từ từ. Đặt tùy chọn này thành true cho phép trình biên dịch xử lý các tệp .js, cho phép việc áp dụng TypeScript dần dần trong một dự án.

Ví dụ:

            {
  "compilerOptions": {
    "allowJs": true
  }
}

`jsx`

Tùy chọn jsx chỉ định cách xử lý cú pháp JSX. Các giá trị phổ biến bao gồm preserve, react, react-native, và react-jsx. preserve giữ lại cú pháp JSX trong đầu ra, trong khi react chuyển đổi JSX thành các lệnh gọi React.createElement. react-jsx sử dụng phép biến đổi JSX mới được giới thiệu trong React 17, không yêu cầu nhập React. Việc chọn đúng tùy chọn JSX là rất quan trọng đối với các dự án sử dụng React hoặc các thư viện dựa trên JSX khác.

Ví dụ:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

`declaration`

Tùy chọn declaration tạo ra các tệp khai báo .d.ts tương ứng cho mỗi tệp TypeScript. Các tệp khai báo chứa thông tin kiểu và được các dự án TypeScript khác sử dụng để tiêu thụ mã đã được biên dịch. Việc tạo các tệp khai báo là rất cần thiết để tạo ra các thư viện và mô-đun có thể tái sử dụng. Các tệp này cho phép các dự án TypeScript khác hiểu được các kiểu và giao diện được phơi bày bởi thư viện mà không cần phải biên dịch mã nguồn gốc.

Ví dụ:

            {
  "compilerOptions": {
    "declaration": true
  }
}

`sourceMap`

Tùy chọn sourceMap tạo ra các tệp source map, ánh xạ mã JavaScript đã tạo trở lại mã TypeScript gốc. Source map rất cần thiết để gỡ lỗi mã TypeScript trong trình duyệt và các môi trường khác. Khi xảy ra lỗi trong mã JavaScript, source map cho phép nhà phát triển xem mã TypeScript tương ứng trong trình gỡ lỗi, giúp việc xác định và khắc phục sự cố dễ dàng hơn.

Ví dụ:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}

`outDir`

Tùy chọn outDir chỉ định thư mục đầu ra cho các tệp JavaScript được tạo. Tùy chọn này giúp tổ chức đầu ra build của dự án bằng cách tách mã nguồn khỏi mã đã biên dịch. Sử dụng outDir giúp quản lý quy trình build và triển khai ứng dụng dễ dàng hơn.

Ví dụ:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}

`rootDir`

Tùy chọn rootDir chỉ định thư mục gốc của dự án TypeScript. Trình biên dịch sử dụng thư mục này làm cơ sở để giải quyết tên mô-đun. Tùy chọn này đặc biệt quan trọng đối với các dự án có cấu trúc thư mục phức tạp. Việc đặt rootDir chính xác đảm bảo rằng trình biên dịch có thể tìm thấy tất cả các mô-đun và phụ thuộc cần thiết.

Ví dụ:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}

`strict`

Tùy chọn strict kích hoạt tất cả các tùy chọn kiểm tra kiểu nghiêm ngặt. Điều này rất được khuyến khích cho các dự án TypeScript mới vì nó giúp phát hiện các lỗi tiềm ẩn sớm trong quá trình phát triển. Kích hoạt chế độ nghiêm ngặt thực thi các quy tắc kiểm tra kiểu chặt chẽ hơn, dẫn đến mã mạnh mẽ và dễ bảo trì hơn. Đây là một thực hành tốt nhất để kích hoạt chế độ nghiêm ngặt trong tất cả các dự án TypeScript mới.

Ví dụ:

            {
  "compilerOptions": {
    "strict": true
  }
}

`esModuleInterop`

Tùy chọn esModuleInterop cho phép khả năng tương tác giữa các mô-đun CommonJS và ES. Điều này quan trọng đối với các dự án sử dụng cả hai loại mô-đun. Khi esModuleInterop được kích hoạt, TypeScript sẽ tự động xử lý sự khác biệt giữa các mô-đun CommonJS và ES, giúp việc nhập và xuất mô-đun giữa hai hệ thống dễ dàng hơn. Tùy chọn này đặc biệt hữu ích khi làm việc với các thư viện của bên thứ ba có thể sử dụng các hệ thống mô-đun khác nhau.

Ví dụ:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}

`moduleResolution`

Tùy chọn moduleResolution chỉ định cách TypeScript giải quyết các lệnh nhập mô-đun. Các giá trị phổ biến bao gồm Node và Classic. Chiến lược giải quyết mô-đun Node là mặc định và dựa trên thuật toán giải quyết mô-đun của Node.js. Chiến lược giải quyết mô-đun Classic cũ hơn và ít được sử dụng hơn. Sử dụng chiến lược giải quyết mô-đun Node đảm bảo rằng TypeScript có thể giải quyết chính xác các lệnh nhập mô-đun trong môi trường Node.js.

Ví dụ:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

`baseUrl` và `paths`

Các tùy chọn baseUrl và paths được sử dụng để cấu hình việc giải quyết mô-đun cho các lệnh nhập mô-đun không tương đối. Tùy chọn baseUrl chỉ định thư mục cơ sở để giải quyết các tên mô-đun không tương đối. Tùy chọn paths cho phép bạn ánh xạ tên mô-đun tới các vị trí cụ thể trên hệ thống tệp. Các tùy chọn này đặc biệt hữu ích cho các dự án có cấu trúc thư mục phức tạp và để đơn giản hóa các lệnh nhập mô-đun. Sử dụng baseUrl và paths có thể làm cho mã dễ đọc và dễ bảo trì hơn.

Ví dụ:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

Tùy chọn Include và Exclude

Các tùy chọn include và exclude chỉ định các tệp nào sẽ được bao gồm trong quá trình biên dịch và các tệp nào sẽ bị loại trừ. Các tùy chọn này sử dụng các mẫu glob để khớp với tên tệp. Sử dụng include và exclude cho phép bạn kiểm soát các tệp nào được xử lý bởi trình biên dịch TypeScript, cải thiện hiệu suất build và giảm thiểu lỗi. Đây là một thực hành tốt nhất để chỉ định rõ ràng các tệp sẽ được bao gồm trong quá trình biên dịch.

Ví dụ:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Tùy chọn Extends

Tùy chọn extends cho phép bạn kế thừa các tùy chọn trình biên dịch từ một tệp tsconfig.json khác. Điều này hữu ích để chia sẻ các cài đặt cấu hình chung giữa nhiều dự án hoặc để tạo các cấu hình cơ sở. Sử dụng tùy chọn extends thúc đẩy việc tái sử dụng mã và giảm sự trùng lặp. Đây là một thực hành tốt nhất để tạo các cấu hình cơ sở và mở rộng chúng trong các dự án riêng lẻ.

Ví dụ:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

Các Cấu hình Nâng cao

Ngoài các tùy chọn trình biên dịch thiết yếu, tsconfig.json còn hỗ trợ các cấu hình nâng cao cho các kịch bản chuyên biệt.

Biên dịch Tăng dần (Incremental Compilation)

Đối với các dự án lớn, biên dịch tăng dần có thể cải thiện đáng kể thời gian build. TypeScript có thể lưu trữ kết quả của các lần biên dịch trước và chỉ biên dịch lại các tệp đã thay đổi. Kích hoạt biên dịch tăng dần có thể giảm đáng kể thời gian build cho các dự án lớn. Điều này đặc biệt quan trọng đối với các dự án có số lượng lớn tệp và phụ thuộc.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Tham chiếu Dự án (Project References)

Tham chiếu dự án cho phép bạn cấu trúc các dự án TypeScript lớn thành các mô-đun nhỏ hơn, độc lập. Điều này có thể cải thiện thời gian build và tổ chức mã. Sử dụng tham chiếu dự án có thể làm cho các dự án lớn dễ quản lý và bảo trì hơn. Đây là một thực hành tốt nhất để sử dụng tham chiếu dự án cho các dự án lớn, phức tạp.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

Định nghĩa Kiểu Tùy chỉnh

Đôi khi, bạn có thể cần cung cấp các định nghĩa kiểu cho các thư viện JavaScript không có chúng. Bạn có thể tạo các tệp .d.ts tùy chỉnh để xác định các kiểu cho các thư viện này. Việc tạo các định nghĩa kiểu tùy chỉnh cho phép bạn sử dụng các thư viện JavaScript trong mã TypeScript của mình mà không phải hy sinh tính an toàn về kiểu. Điều này đặc biệt hữu ích khi làm việc với mã JavaScript cũ hoặc các thư viện không cung cấp định nghĩa kiểu riêng.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

Các Thực hành Tốt nhất

Sử dụng Chế độ Nghiêm ngặt: Kích hoạt tùy chọn strict để tăng cường kiểm tra kiểu.
Chỉ định Target: Chọn phiên bản target phù hợp cho môi trường chạy của bạn.
Tổ chức Đầu ra: Sử dụng outDir để tách mã nguồn khỏi mã đã biên dịch.
Quản lý Phụ thuộc: Sử dụng include và exclude để kiểm soát các tệp nào được biên dịch.
Tận dụng Extends: Chia sẻ các cài đặt cấu hình chung với tùy chọn extends.
Đưa Cấu hình vào Kiểm soát Phiên bản: Commit tsconfig.json vào git để duy trì tính nhất quán trên các môi trường của nhà phát triển và các quy trình CI/CD.

Xử lý các Sự cố Thường gặp

Việc cấu hình tsconfig.json đôi khi có thể gặp khó khăn. Dưới đây là một số sự cố thường gặp và giải pháp của chúng:

Sự cố về Giải quyết Mô-đun

Nếu bạn gặp lỗi về giải quyết mô-đun, hãy đảm bảo rằng tùy chọn moduleResolution được cấu hình chính xác và các tùy chọn baseUrl và paths được thiết lập đúng cách. Kiểm tra kỹ các đường dẫn được chỉ định trong tùy chọn paths để đảm bảo chúng chính xác. Xác minh rằng tất cả các mô-đun cần thiết đã được cài đặt trong thư mục node_modules.

Lỗi Kiểu

Lỗi kiểu có thể xảy ra nếu các định nghĩa kiểu không chính xác hoặc bị thiếu. Hãy đảm bảo rằng bạn đã cài đặt đúng các định nghĩa kiểu cho tất cả các thư viện bạn đang sử dụng. Nếu bạn đang sử dụng một thư viện JavaScript không có định nghĩa kiểu, hãy xem xét việc tạo các định nghĩa kiểu tùy chỉnh.

Lỗi Biên dịch

Lỗi biên dịch có thể xảy ra nếu có lỗi cú pháp hoặc lỗi kiểu trong mã TypeScript của bạn. Hãy xem xét kỹ các thông báo lỗi và sửa bất kỳ lỗi cú pháp hoặc lỗi kiểu nào. Đảm bảo rằng mã của bạn tuân thủ các quy ước mã hóa của TypeScript.

Kết luận

Một tệp tsconfig.json được cấu hình tốt là điều cần thiết cho một dự án TypeScript thành công. Bằng cách hiểu các tùy chọn trình biên dịch thiết yếu và các cấu hình nâng cao, bạn có thể tối ưu hóa quy trình làm việc phát triển của mình, cải thiện chất lượng mã và đảm bảo tính tương thích với môi trường mục tiêu. Việc đầu tư thời gian vào việc cấu hình tsconfig.json đúng cách sẽ mang lại lợi ích lâu dài bằng cách giảm thiểu lỗi, cải thiện khả năng bảo trì và hợp lý hóa quy trình build. Điều này dẫn đến việc phát triển phần mềm hiệu quả và đáng tin cậy hơn. Thông tin được cung cấp ở đây được thiết kế để có thể áp dụng phổ biến và sẽ cung cấp một nền tảng vững chắc để bắt đầu một dự án mới với TypeScript.

Hãy nhớ tham khảo tài liệu chính thức của TypeScript để có thông tin cập nhật nhất và giải thích chi tiết về tất cả các tùy chọn trình biên dịch có sẵn. Tài liệu TypeScript là một nguồn tài nguyên quý giá để hiểu các điểm phức tạp của cấu hình TypeScript.

Cấu hình TypeScript: Hướng dẫn Toàn diện về tsconfig.json

tsconfig.json là gì?

Tạo tệp tsconfig.json

Các Tùy chọn Trình biên dịch Thiết yếu

target

module

lib

allowJs

jsx

declaration

sourceMap

outDir

rootDir

strict

esModuleInterop

moduleResolution

baseUrl và paths

Tùy chọn Include và Exclude

Tùy chọn Extends

Các Cấu hình Nâng cao

Biên dịch Tăng dần (Incremental Compilation)

Tham chiếu Dự án (Project References)

Định nghĩa Kiểu Tùy chỉnh

Các Thực hành Tốt nhất

Xử lý các Sự cố Thường gặp

Sự cố về Giải quyết Mô-đun

Lỗi Kiểu

Lỗi Biên dịch

Kết luận

`target`

`module`

`lib`

`allowJs`

`jsx`

`declaration`

`sourceMap`

`outDir`

`rootDir`

`strict`

`esModuleInterop`

`moduleResolution`

`baseUrl` và `paths`