Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

License

Quản lý giấy phép trong toàn bộ workspace của bạn: đồng bộ hóa các tệp LICENSE và tiêu đề mã nguồn cho mã của riêng bạn (license.source), và kiểm tra rằng mọi dependency tuân thủ danh sách giấy phép được phép (license.dependencies).

Cách sử dụng

Phần tiêu đề “Cách sử dụng”

Chạy Trình tạo

Phần tiêu đề “Chạy Trình tạo”
Terminal window
pnpm nx g @aws/nx-plugin:license
Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi
Terminal window
pnpm nx g @aws/nx-plugin:license --dry-run

Tùy chọn

Phần tiêu đề “Tùy chọn”
Tham sốKiểuMặc địnhMô tả
license Apache-2.0 | MIT | ASLApache-2.0Mã định danh giấy phép SPDX cho giấy phép bạn đã chọn
copyrightHolder stringAmazon.com, Inc. or its affiliatesNgười giữ bản quyền, được bao gồm trong tệp LICENSE và phần đầu của các tệp mã nguồn theo mặc định.
dependencyCheck booleantrueCấu hình một target license-check sẽ thất bại khi các dependency khai báo giấy phép nằm ngoài danh sách cho phép đã cấu hình.
preferInstallDependencies booleantrueCó nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator cùng lúc (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Trình tạo

Phần tiêu đề “Kết quả của Trình tạo”

Trình tạo sẽ tạo hoặc cập nhật các tệp sau:

  • nx.json Target lint được cấu hình để chạy trình tạo đồng bộ license và phụ thuộc vào target license-check
  • aws-nx-plugin.config.mts Cấu hình cho đồng bộ nguồn license (license.source) và kiểm tra dependency (license.dependencies)

Tiêu đề & Tệp License

Phần tiêu đề “Tiêu đề & Tệp License”

Trình tạo đăng ký một sync generator để thực thi như một phần của các target lint của bạn, đảm bảo rằng các tệp nguồn của bạn chứa tiêu đề license chính xác, các dự án của bạn chứa tệp LICENSE, và metadata giấy phép được thiết lập trong package.json và pyproject.toml.

Quy trình làm việc

Phần tiêu đề “Quy trình làm việc”

Bất cứ khi nào bạn build các dự án của mình (và target lint chạy), trình tạo đồng bộ license sẽ đảm bảo rằng giấy phép trong dự án của bạn khớp với cấu hình của bạn. Nếu nó phát hiện bất kỳ điều gì không đồng bộ, bạn sẽ nhận được thông báo như sau:

Terminal window
  NX   The workspace is out of sync


[@aws/nx-plugin:license#sync]: Project LICENSE files are out of sync:
- LICENSE
- packages/<my-project>LICENSE


Project package.json files are out of sync:
- package.json


Project pyproject.toml files are out of sync:
- pyproject.toml
- packages/<my-python-project>/pyproject.toml


License headers are out of sync in the following source files:
- packages/<my-project>/src/index.ts
- packages/<my-python-project>/main.py


This will result in an error in CI.


? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Chọn Yes để đồng bộ các thay đổi.

Hành vi Đồng bộ

Phần tiêu đề “Hành vi Đồng bộ”

Trình tạo đồng bộ license thực hiện ba tác vụ chính:

1. Đồng bộ hóa Tiêu đề License của Tệp Nguồn

Phần tiêu đề “1. Đồng bộ hóa Tiêu đề License của Tệp Nguồn”

Khi trình tạo đồng bộ được chạy, nó sẽ đảm bảo rằng tất cả các tệp mã nguồn trong workspace của bạn (dựa trên cấu hình của bạn) chứa tiêu đề license phù hợp. Tiêu đề được viết dưới dạng khối comment đầu tiên hoặc chuỗi liên tiếp các comment dòng trong tệp (ngoài shebang/hashbang nếu có trong tệp).

2. Đồng bộ hóa Tệp LICENSE

Phần tiêu đề “2. Đồng bộ hóa Tệp LICENSE”

Khi trình tạo đồng bộ được chạy, nó sẽ đảm bảo rằng tệp LICENSE gốc tương ứng với giấy phép đã cấu hình của bạn, cũng như đảm bảo rằng tất cả các dự án con trong workspace của bạn cũng chứa tệp LICENSE chính xác.

3. Đồng bộ hóa thông tin giấy phép trong các tệp dự án

Phần tiêu đề “3. Đồng bộ hóa thông tin giấy phép trong các tệp dự án”

Khi trình tạo đồng bộ được chạy, nó sẽ đảm bảo các trường license trong các tệp package.json và pyproject.toml được đặt thành giấy phép đã cấu hình của bạn.

Cấu hình Tiêu đề & Tệp

Phần tiêu đề “Cấu hình Tiêu đề & Tệp”

Cấu hình được định nghĩa trong tệp aws-nx-plugin.config.mts ở thư mục gốc của workspace của bạn.

SPDX và Chủ sở hữu Bản quyền

Phần tiêu đề “SPDX và Chủ sở hữu Bản quyền”

Giấy phép bạn chọn có thể được cập nhật bất cứ lúc nào thông qua thuộc tính cấu hình spdx:

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      spdx: 'MIT',
    },
  },
} satisfies AwsNxPluginConfig;

Khi trình tạo đồng bộ chạy, tất cả các tệp LICENSE, package.json và pyproject.toml sẽ được cập nhật để phản ánh giấy phép đã cấu hình.

Bạn có thể cấu hình thêm chủ sở hữu bản quyền và năm bản quyền, được bao gồm trong một số tệp LICENSE:

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      spdx: 'MIT',
      copyrightHolder: 'Amazon.com, Inc. or its affiliates',
      copyrightYear: 2025,
    },
  },
} satisfies AwsNxPluginConfig;

Nội dung Tiêu đề License

Phần tiêu đề “Nội dung Tiêu đề License”

Nội dung tiêu đề license có thể được cấu hình theo hai cách:

  1. Sử dụng nội dung inline:
aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          lines: [
            'Copyright: My Company, Incorporated.',
            'Licensed under the MIT License',
            'All rights reserved',
          ];
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;
  1. Tải từ một tệp:
aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          filePath: 'license-header.txt'; // relative to workspace root
        }
        // ... format configuration
      }
    }
  }
} satisfies AwsNxPluginConfig;

Định dạng Tiêu đề

Phần tiêu đề “Định dạng Tiêu đề”

Bạn có thể chỉ định cách tiêu đề license nên được định dạng cho các loại tệp khác nhau bằng cách sử dụng các mẫu glob. Cấu hình định dạng hỗ trợ comment dòng, comment khối, hoặc kết hợp cả hai:

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['Copyright notice here'],
        },
        format: {
          // Line comments
          '**/*.ts': {
            lineStart: '// ',
          },
          // Block comments
          '**/*.css': {
            blockStart: '/*',
            blockEnd: '*/',
          },
          // Block comments with line prefixes
          '**/*.java': {
            blockStart: '/*',
            lineStart: ' * ',
            blockEnd: ' */',
          },
          // Line comments with header/footer
          '**/*.py': {
            blockStart: '# ------------',
            lineStart: '# ',
            blockEnd: '# ------------',
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

Cấu hình định dạng hỗ trợ:

  • blockStart: Văn bản được viết trước nội dung license (ví dụ: để bắt đầu một comment khối)
  • lineStart: Văn bản được thêm vào đầu mỗi dòng của nội dung license
  • lineEnd: Văn bản được thêm vào cuối mỗi dòng của nội dung license
  • blockEnd: Văn bản được viết sau nội dung license (ví dụ: để kết thúc một comment khối)

Cú pháp Comment Tùy chỉnh

Phần tiêu đề “Cú pháp Comment Tùy chỉnh”

Đối với các loại tệp không được hỗ trợ sẵn, bạn có thể chỉ định cú pháp comment tùy chỉnh để cho trình tạo đồng bộ biết cách xác định các tiêu đề license hiện có trong các loại tệp này.

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.xyz': {
            lineStart: '## ',
          },
        },
        commentSyntax: {
          xyz: {
            line: '##', // Define line comment syntax
          },
          abc: {
            block: {
              // Define block comment syntax
              start: '<!--',
              end: '-->',
            },
          },
        },
      },
    },
  },
} satisfies AwsNxPluginConfig;

Loại trừ Tệp khỏi Đồng bộ Tiêu đề

Phần tiêu đề “Loại trừ Tệp khỏi Đồng bộ Tiêu đề”

Theo mặc định, trong một kho git, tất cả các tệp .gitignore được tôn trọng để đảm bảo rằng chỉ các tệp được quản lý bởi version control mới được đồng bộ hóa. Trong các kho không phải git, tất cả các tệp được xem xét trừ khi được loại trừ rõ ràng trong cấu hình.

Bạn có thể loại trừ các tệp bổ sung khỏi đồng bộ hóa tiêu đề license bằng cách sử dụng các mẫu glob:

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      header: {
        content: {
          lines: ['My license header'],
        },
        format: {
          '**/*.ts': {
            lineStart: '// ',
          },
        },
        exclude: ['**/generated/**', '**/dist/**', 'some-specific-file.ts'],
      },
    },
  },
} satisfies AwsNxPluginConfig;

Loại trừ Dự án khỏi Đồng bộ Tệp

Phần tiêu đề “Loại trừ Dự án khỏi Đồng bộ Tệp”

Tất cả các tệp LICENSE, tệp package.json và tệp pyproject.toml được đồng bộ hóa với giấy phép đã cấu hình theo mặc định.

Bạn có thể loại trừ các dự án hoặc tệp cụ thể khỏi đồng bộ hóa bằng cách sử dụng các mẫu glob:

aws-nx-plugin.config.mts
export default {
  license: {
    source: {
      files: {
        exclude: [
          // do not sync LICENSE file, package.json or pyproject.toml
          'packages/excluded-project',
          // do not sync LICENSE file, but sync package.json and/or pyproject.toml
          'apps/internal/LICENSE',
        ];
      }
    }
  }
} satisfies AwsNxPluginConfig;

Vô hiệu hóa Đồng bộ License

Phần tiêu đề “Vô hiệu hóa Đồng bộ License”

Đồng bộ nguồn license được kích hoạt bởi sự hiện diện của khóa license.source trong cấu hình của bạn. Để vô hiệu hóa nó:

  1. Xóa phần license.source khỏi cấu hình của bạn trong aws-nx-plugin.config.mts (bạn có thể giữ license.dependencies nếu bạn vẫn muốn kiểm tra giấy phép dependency)
  2. Nếu bạn cũng muốn xóa hoàn toàn trình tạo đồng bộ, hãy xóa trình tạo @aws/nx-plugin:license#sync khỏi targetDefaults.lint.syncGenerators

Để kích hoạt lại đồng bộ license, chỉ cần chạy lại trình tạo license.

Kiểm tra License Dependency

Phần tiêu đề “Kiểm tra License Dependency”

Trình tạo license cũng cấu hình một target license-check sẽ thất bại khi một trong các dependency của dự án của bạn (hoặc bất kỳ dependency bắc cầu nào) khai báo một giấy phép không có trong danh sách cho phép của bạn.

Cách nó chạy

Phần tiêu đề “Cách nó chạy”

Trình tạo viết một target license-check vào project.json gốc của bạn:

project.json
{
  "targets": {
    "license-check": {
      "executor": "@aws/nx-plugin:license-check",
      "cache": true,
      "inputs": [
        "{workspaceRoot}/pnpm-lock.yaml",
        "{workspaceRoot}/aws-nx-plugin.config.mts"
      ],
      "options": {}
    }
  }
}

Các inputs được tính toán cho workspace của bạn: chỉ các tệp lockfile thực sự có mặt mới được bao gồm, cùng với aws-nx-plugin.config.mts, cộng với một glob {workspaceRoot}/**/uv.lock khi kiểm tra dependency Python được bật (tức là một collector Python được cấu hình).

Bạn có thể chạy kiểm tra trực tiếp:

Terminal window
pnpm nx license-check

Kết quả được lưu vào bộ nhớ cache dựa trên các tệp lockfile và aws-nx-plugin.config.mts của bạn — các lần chạy lại là tức thì khi không có gì thay đổi.

Các collector xác định những gì được quét. npmCollector sử dụng license-checker-rseidelsohn, và pythonCollector sử dụng pip-licenses. Nếu không tìm thấy dependency đã cài đặt nào, kiểm tra sẽ vượt qua mà không có gì để kiểm tra.

Chạy như một phần của lint/build

Phần tiêu đề “Chạy như một phần của lint/build”

Kiểm tra license dependency chạy tự động bất cứ khi nào bạn lint hoặc build bất kỳ dự án nào trong workspace của bạn. Trình tạo license kết nối target lint của mỗi dự án để phụ thuộc vào target license-check gốc, và các trình tạo dự án (ts#* và py#*) làm tương tự khi chúng chạy — vì vậy kiểm tra được kết nối bất kể thứ tự các trình tạo được chạy.

Điều này có nghĩa là bạn không cần chạy kiểm tra một cách rõ ràng, mặc dù bạn vẫn có thể làm như vậy với target license-check:

Terminal window
pnpm nx license-check

Kết nối là một dependsOn xuyên dự án trên target lint của mỗi dự án trỏ đến target license-check gốc. Để bỏ qua kiểm tra trong quá trình lint hoặc build, hãy đặt biến môi trường LICENSE_DEPENDENCY_CHECK=skip:

Terminal window
pnpm LICENSE_DEPENDENCY_CHECK=skip lint

Cấu hình

Phần tiêu đề “Cấu hình”

Theo mặc định, kiểm tra sử dụng một tập hợp các giấy phép cho phép phổ biến được tích hợp sẵn (MIT, Apache-2.0, BSD, ISC, v.v.) được xuất dưới dạng DEFAULT_LICENSE_ALLOWLIST. Bạn có thể mở rộng hoặc ghi đè điều này trong cấu hình của bạn:

aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';


export default {
  license: {
    // ...
    dependencies: {
      allow: [...DEFAULT_LICENSE_ALLOWLIST, { spdxId: 'LGPL-2.1-or-later', fullName: 'GNU Lesser General Public License v2.1 or later', aliases: [] }],
      exceptions: [
        { package: 'some-package', reason: 'Audited manually — ships MIT text without SPDX field' },
      ],
    },
  },
} satisfies AwsNxPluginConfig;
Xem danh sách đầy đủ các giấy phép trong DEFAULT_LICENSE_ALLOWLIST

Tùy chỉnh danh sách cho phép

Phần tiêu đề “Tùy chỉnh danh sách cho phép”

Để hạn chế danh sách cho phép, hãy thay thế DEFAULT_LICENSE_ALLOWLIST bằng mảng của riêng bạn. Để mở rộng nó, hãy spread mặc định và thêm các mục. Các mục được khớp theo id SPDX, tên giấy phép đầy đủ, hoặc bất kỳ bí danh nào được liệt kê (không phân biệt chữ hoa chữ thường).

Ngoại lệ cho từng package

Phần tiêu đề “Ngoại lệ cho từng package”

Sử dụng exceptions cho các package không vượt qua kiểm tra — hoặc vì giấy phép của chúng không có trong danh sách cho phép, hoặc vì chúng được giao mà không có metadata giấy phép có thể phát hiện được. Trường reason là bắt buộc để người đánh giá có thể thấy lý do tại sao ngoại lệ được cấp.

exceptions: [
  {
    package: 'union',
    version: '0.5.0',
    reason: 'Package ships verbatim MIT text without declaring license',
  },
];

Các trình tạo giới thiệu các dependency với metadata có vấn đề (ví dụ: trình tạo máy chủ MCP) tự động thêm các ngoại lệ cần thiết vào cấu hình của bạn khi chúng chạy.

Collectors

Phần tiêu đề “Collectors”

Các collector khám phá các dependency và trích xuất metadata giấy phép. Các collector tích hợp sẵn là npmCollector() (quét node_modules) và pythonCollector() (quét các môi trường ảo Python). Trình tạo license cấu hình npmCollector() theo mặc định và thêm pythonCollector() khi có các dự án Python.

Để triển khai một collector tùy chỉnh, hãy tuân thủ giao diện LicenseCollector:

import type { LicenseCollector } from '@aws/nx-plugin/sdk/license';


const myCollector = (): LicenseCollector => ({
  name: 'my-ecosystem',
  traceCommand: 'my-tool why <package>',
  async collect({ workspaceRoot }) {
    return [
      { name: 'some-dep', version: '1.0.0', rawLicense: 'MIT', ecosystem: 'my-ecosystem' },
    ];
  },
});

Hook onDependency

Phần tiêu đề “Hook onDependency”

license.dependencies chấp nhận một callback onDependency tùy chọn được gọi một lần cho mỗi dependency được phát hiện, bất kể nó vượt qua hay thất bại kiểm tra. Nó nhận { package, spdx }, trong đó package là tên package và spdx là biểu thức giấy phép SPDX đã được giải quyết. spdx của một ngoại lệ được ưu tiên hơn giấy phép được khai báo thô, và spdx có thể là một chuỗi rỗng nếu không có giấy phép nào được khai báo.

Đây là một cách tiện lợi để in ra tất cả các giấy phép trong dự án của bạn. Chạy target license-check để xem đầu ra:

aws-nx-plugin.config.mts
import { AwsNxPluginConfig } from '@aws/nx-plugin';
import { DEFAULT_LICENSE_ALLOWLIST } from '@aws/nx-plugin/sdk/license';


export default {
  license: {
    dependencies: {
      allow: DEFAULT_LICENSE_ALLOWLIST,
      onDependency: ({ package: pkg, spdx }) => {
        console.log(`${pkg} - ${spdx}`);
      },
    },
  },
} satisfies AwsNxPluginConfig;

Vô hiệu hóa Kiểm tra Dependency

Phần tiêu đề “Vô hiệu hóa Kiểm tra Dependency”

Kiểm tra license dependency được kích hoạt bởi sự hiện diện của khóa license.dependencies trong cấu hình của bạn.

Để vô hiệu hóa kiểm tra cho một lần chạy duy nhất, hãy đặt biến môi trường LICENSE_DEPENDENCY_CHECK=skip:

Terminal window
pnpm LICENSE_DEPENDENCY_CHECK=skip lint

Để vô hiệu hóa vĩnh viễn, hãy xóa khóa license.dependencies khỏi cấu hình của bạn trong aws-nx-plugin.config.mts. Bạn cũng có thể chạy lại trình tạo license với --dependencyCheck=false để tạo scaffold mà không có nó.