Cách viết một thư viện JavaScript với Vite + tsdown + Rolldown + pnpm

Bài viết này mình sẽ hướng dẫn tạo một thư viện JavaScript/TypeScript dùng pnpm, từ dev, test local, đến publish lên npm. Stack: TypeScript, tsdown (build với Rolldown), Vitest, pnpm, output ESM only, test local qua file: protocol.

1. Tổng quan stack

2. Khởi tạo thư viện

mkdir my-lib
cd my-lib
pnpm init

package.json

{
 "name": "my-lib",
 "version": "0.0.1",
 "type": "module",
 "main": "./dist/index.mjs",
 "types": "./dist/index.d.mts",
 "exports": {
 ".": {
 "types": "./dist/index.d.mts",
 "import": "./dist/index.mjs"
 }
 },
 "files": ["dist"],
 "scripts": {
 "dev": "tsdown --watch",
 "build": "tsdown",
 "test": "vitest run",
 "test:watch": "vitest",
 "prepublishOnly": "pnpm build"
 },
 "packageManager": "pnpm@10.25.0"
}

Một số điểm quan trọng:

• "type": "module" — toàn bộ project dùng ESM.
• main và exports trỏ vào dist/index.mjs — tsdown mặc định xuất .mjs cho ESM output.
• files: ["dist"] — chỉ publish thư mục dist, không push src/test/config lên npm.
• prepublishOnly — tự động build trước khi publish, đảm bảo dist luôn mới nhất.

Cài dependencies

pnpm add -D tsdown typescript vitest unrun

unrun là peer dependency runtime của tsdown, cần cài tường minh.

3. Cấu hình TypeScript

tsconfig.json

{
 "compilerOptions": {
 "target": "ES2022",
 "module": "ESNext",
 "moduleResolution": "bundler",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true,
 "declaration": true,
 "declarationDir": "./dist",
 "outDir": "./dist",
 "rootDir": "./src"
 },
 "include": ["src"],
 "exclude": ["node_modules", "dist"]
}

• "moduleResolution": "bundler" — tương thích với tsdown/Rolldown.
• "declaration": true — tạo .d.ts làm nguồn cho tsdown dùng với plugin rolldown-plugin-dts.

4. Cấu hình Build với tsdown

tsdown là bundler chuyên cho thư viện, built on Rolldown, của cùng team làm Vite.

tsdown.config.ts

import { defineConfig } from "tsdown";

export default defineConfig({
 entry: ["src/index.ts"],
 outDir: "dist",
 format: ["esm"],
 dts: true,
 clean: true,
});

• format: ["esm"] — chỉ xuất ESM (.mjs).
• dts: true — tự động generate type declarations qua rolldown-plugin-dts.
• clean: true — xóa dist trước mỗi lần build.

.gitignore

node_modules
dist
*.log

Không commit dist/. Chỉ generate khi publish.

5. Viết code

src/index.ts

export function greet(name: string): string {
 return `Hello, ${name}!`;
}

export function sum(a: number, b: number): number {
 return a + b;
}

6. Viết test

vitest.config.ts

import { defineConfig } from "vitest/config";

export default defineConfig({
 test: {
 include: ["tests/**/*.test.ts"],
 },
});

tests/index.test.ts

import { describe, it, expect } from "vitest";
import { greet, sum } from "../src/index";

describe("greet", () => {
 it("returns greeting with name", () => {
 expect(greet("World")).toBe("Hello, World!");
 });
});

describe("sum", () => {
 it("adds two numbers", () => {
 expect(sum(1, 2)).toBe(3);
 });
});

pnpm test # chạy test 1 lần
pnpm test:watch # watch mode

7. Build

pnpm build

Output:

dist/
├── index.mjs ← bundle ESM
└── index.d.mts ← type declarations

8. Test local (giống như consumer thật)

Không cần publish lên npm để test. Dùng file: protocol.

Tạo project consumer

mkdir ../my-lib-test
cd ../my-lib-test
pnpm init

package.json của consumer

{
 "name": "my-lib-test",
 "private": true,
 "type": "module",
 "scripts": {
 "start": "tsx src/index.ts"
 },
 "dependencies": {
 "my-lib": "file:../my-lib"
 },
 "devDependencies": {
 "tsx": "^4.19.0",
 "typescript": "^5.8.0"
 }
}

"my-lib": "file:../my-lib" — pnpm tạo symlink từ my-lib-test/node_modules/my-lib → my-lib/dist. Mỗi lần build lại lib, consumer dùng code mới ngay, không cần pnpm install lại.

src/index.ts của consumer

import { greet, sum } from "my-lib";

console.log(greet("a"));
console.log("1 + 2 =", sum(1, 2));

Chạy

pnpm install
pnpm start

Hello, a!
1 + 2 = 3

9. Quy trình dev hàng ngày

# Terminal 1 — lib
cd my-lib
pnpm dev # watch mode, auto build khi code thay đổi

# Terminal 2 — consumer
cd my-lib-test
pnpm start # chạy lại để test code mới

Hoặc không cần watch:

cd my-lib && pnpm build # build một lần
cd my-lib-test && pnpm start

10. Publish lên npm

cd my-lib

# Đảm bảo đã login
pnpm whoami # kiểm tra, nếu chưa: pnpm login

# Đảm bảo code sạch, test pass
pnpm test

# Publish (prepublishOnly sẽ tự chạy build)
pnpm publish

Lần publish đầu tiên nên thêm --access public nếu package không scoped:

pnpm publish --access public

Các lần sau tăng version rồi publish:

pnpm version patch # 0.0.1 → 0.0.2
# hoặc: minor (0.1.0), major (1.0.0)
pnpm publish

11. Cấu trúc thư mục cuối cùng

my-lib/
├── src/
│ └── index.ts
├── tests/
│ └── index.test.ts
├── package.json
├── tsconfig.json
├── tsdown.config.ts
├── vitest.config.ts
└── .gitignore

my-lib-test/
├── src/
│ └── index.ts
├── package.json

12. Một số lưu ý

• tsdown đang phát triển nhanh — nếu gặp lỗi peer dependency như unmet peer typescript@^6.0.0, có thể bỏ qua hoặc cài thêm unrun nếu thiếu.
• Không bundle dependencies — nếu lib có dependency bên ngoài, thêm vào package.json dependency và config tsdown.config.ts với external: true.
• Muốn xuất CJS? Sửa format: ["esm", "cjs"] trong tsdown.config.ts, output sẽ thêm index.cjs + index.d.cts.
• Scoped package? Đổi "name": "@scope/my-lib" trong package.json, publish với --access public.
  
  
  Cảm ơn bác bạn đã đọc bài viết!