Posted inDevelopment

Tự xây dựng VS Code Extension: Từ ý tưởng đến file .vsix thực chiến

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Nỗi khổ khi thiếu công cụ “đo ni đóng giày”

Bạn đã bao giờ tốn 15-20 phút mỗi ngày chỉ để copy-paste đoạn header bản quyền vào hàng chục file code chưa? Dù Marketplace có hàng nghìn extension, đôi khi chúng ta vẫn rơi vào cảnh “lực bất tòng tâm”. Workflow của mỗi dự án thường rất đặc thù, khiến không công cụ sẵn có nào đáp ứng nổi.

Mình từng tham gia refactor một codebase khổng lồ hơn 50.000 dòng lệnh. Bài học lớn nhất mình rút ra là: nếu không tự động hóa các thao tác nhàm chán, bạn sẽ kiệt sức trước khi kịp chạm vào logic chính. Thay vì chọn cách thủ công dễ sai sót, mình quyết định tự viết extension để giải quyết bài toán của chính mình.

Chuẩn bị “đồ nghề” trước khi bắt tay vào code

Xây dựng extension không khó như bạn nghĩ. Bạn chỉ cần nắm vững JavaScript/TypeScript và cài đặt vài công cụ cơ bản. Vì VS Code chạy trên nền Electron, Node.js sẽ là nền tảng cốt lõi của chúng ta.

Trước tiên, hãy cài đặt Node.js (khuyên dùng bản v18 trở lên). Sau đó, bạn cần cài Yeoman và VS Code Extension Generator. Đây là bộ khung giúp tạo dự án nhanh chóng, giúp bạn tránh khỏi việc phải cấu hình tay lằng nhằng.

npm install -g yo generator-code

Sử dụng bộ generator này giúp mình loại bỏ hoàn toàn các lỗi vặt về cấu trúc thư mục mà người mới thường gặp phải.

Khởi tạo dự án đầu tay

Mọi thứ đã sẵn sàng. Giờ là lúc mở terminal và gõ lệnh để bắt đầu:

yo code

Một trình điều hướng sẽ hiện ra ngay lập tức. Dưới đây là các tùy chọn mình thường ưu tiên cho một dự án thực tế:

  • What type of extension?: New Extension (TypeScript) – Giúp bắt lỗi tốt hơn nhờ cơ chế check type.
  • What’s the name of your extension?: MyCustomHelper
  • What’s the identifier?: my-custom-helper
  • Initialize a git repository?: Yes
  • Bundle the source code with webpack?: No (giữ đơn giản để dễ debug).
  • Which package manager to use?: npm

Chỉ mất khoảng 10 giây, thư mục dự án sẽ hiện ra. Bạn gõ code . để bắt đầu “múa phím”.

Giải mã “trái tim” của một Extension

Đừng vội lao vào viết code logic ngay. File quan trọng nhất bạn cần hiểu thực tế lại là package.json. Đây là nơi khai báo cách extension tương tác với editor.

Hãy chú ý đặc biệt đến hai mục sau:

  1. activationEvents: Định nghĩa thời điểm extension “thức dậy” (ví dụ: khi mở file .ts hoặc chạy một lệnh cụ thể).
  2. contributes: Nơi đăng ký các tính năng như menu, phím tắt hoặc các lệnh (commands).

Tiếp theo là src/extension.ts. Mọi phép thuật đều nằm ở hàm activate(). Đây là nơi bạn đăng ký logic xử lý khi người dùng tương tác.

Thực hành: Tạo lệnh chèn Header bản quyền tự động

Hãy thử tạo tính năng chèn thông tin tác giả vào đầu file chỉ với một phím tắt. Đầu tiên, bạn khai báo lệnh trong package.json:

"contributes": {
  "commands": [
    {
      "command": "my-custom-helper.insertHeader",
      "title": "Insert License Header"
    }
  ]
}

Sau đó, viết logic xử lý trong src/extension.ts. Đoạn code này sẽ xác định vị trí đầu file và chèn nội dung vào:

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    let disposable = vscode.commands.registerCommand('my-custom-helper.insertHeader', () => {
        const editor = vscode.window.activeTextEditor;
        if (!editor) return;

        const header = `/**\n * Author: Dev Chuyên Nghiệp\n * Created: ${new Date().toLocaleDateString()}\n */\n`;
        editor.edit(editBuilder => {
            editBuilder.insert(new vscode.Position(0, 0), header);
        });
        vscode.window.showInformationMessage('Đã thêm Header thành công!');
    });
    context.subscriptions.push(disposable);
}

Một mẹo nhỏ: Luôn kiểm tra activeTextEditor. Nếu người dùng chưa mở file nào mà chạy lệnh, extension của bạn sẽ không bị crash vô duyên.

Kiểm tra và Đóng gói file .vsix

Để chạy thử, bạn chỉ cần nhấn F5. Một cửa sổ VS Code mới sẽ hiện ra để bạn test tính năng. Nhấn Ctrl+Shift+P, gõ “Insert License Header” và tận hưởng thành quả.

Khi mọi thứ đã mượt mà, hãy đóng gói nó để gửi cho đồng nghiệp. Chúng ta dùng công cụ vsce:

npm install -g @vscode/vsce
vsce package

Lệnh này tạo ra một file .vsix duy nhất. Bạn chỉ cần gửi file này đi, người nhận chọn “Install from VSIX…” là xong, không cần upload lên Marketplace công khai.

Tránh bẫy hiệu năng khi làm Extension

Sai lầm lớn nhất của mình hồi mới bắt đầu là nhồi nhét quá nhiều tính năng. Việc này khiến VS Code khởi động chậm chạp và tốn RAM. Hãy giữ cho extension tinh gọn nhất có thể.

Thay vì dùng onStartupFinished, hãy chỉ kích hoạt extension khi thực sự cần thiết qua onCommand. Tự viết công cụ không chỉ giúp làm việc nhanh hơn mà còn giúp bạn hiểu sâu cách các editor hiện đại vận hành bên dưới lớp vỏ UI hào nhoáng.

Share:
Tags: