TypeScriptで自作したnpmパッケージをゼロから作成しGithub ActionsでCI/CDするハンズオン

# 🚀 TypeScript で文字列整形パッケージ `string-sanitizer` を開発・公開・Docs化・CI/CD する完全ガイド

本記事では、HTMLタグ・特殊文字・余分な空白を除去するユーティリティ関数を提供するTypeScript製のNPMパッケージ「`string-sanitizer`」を、ゼロから作成・公開・ドキュメント生成・CI/CD設定するまでの手順を解説します。

初心者の方でもステップ・バイ・ステップで実践できる内容となっています。

---

## ✅ Step 1: プロジェクトの初期化

まず、ディレクトリを作成して Node.js プロジェクトとして初期化します。

```bash
mkdir string-sanitizer
cd string-sanitizer
npm init -y
```

---

## ✅ Step 2: TypeScript を導入・設定

### TypeScript のインストール

```bash
npm install --save-dev typescript
```

### `tsconfig.json` の生成と編集

```bash
npx tsc --init
```

以下のように編集します：

```json
{
  "compilerOptions": {
    "target": "ES2015",
    "module": "CommonJS",
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

---

## ✅ Step 3: ソースコードを実装

```bash
mkdir src
touch src/index.ts
```

### 実装例：`src/index.ts`

```ts
/**
 * 文字列からHTMLタグ、特殊文字、余分な空白を除去します。
 *
 * @param input 処理対象の文字列
 * @returns 整形後のクリーンな文字列
 */
export function sanitize(input: string): string {
  return input
    .replace(/<[^>]*>/g, '')       // HTMLタグを除去
    .replace(/[^\w\s]/gi, '')      // 特殊文字を除去
    .replace(/\s+/g, ' ')          // 連続した空白を単一スペースに置換
    .trim();                       // 前後の空白を除去
}
```

---

## ✅ Step 4: ビルド設定

### `package.json` にビルドスクリプトを追加

```json
"scripts": {
  "build": "tsc"
}
```

### ビルド実行

```bash
npm run build
```

---

## ✅ Step 5: 公開準備

### `package.json` を編集

```json
{
  "name": "string-sanitizer",
  "version": "1.0.0",
  "description": "Sanitize strings by removing HTML, special characters, and extra whitespace.",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "keywords": ["sanitize", "string", "html", "typescript", "utility"],
  "author": "Your Name",
  "license": "MIT"
}
```

### `.npmignore` を作成（任意）

```
src/
tsconfig.json
```

---

## ✅ Step 6: README の作成

````md
# string-sanitizer

A lightweight utility to sanitize strings by removing HTML tags, special characters, and extra whitespace.

## Installation

npm install string-sanitizer

## Usage

import { sanitize } from 'string-sanitizer';

console.log(sanitize("  Hello <b>world</b>! 😃  ")); // Hello world

````

---

## ✅ Step 7: NPM に公開

### ログイン

```bash
npm login
````

👉 アカウントがない場合：[https://www.npmjs.com/signup](https://www.npmjs.com/signup)

### 公開

```bash
npm publish --access public
```

---

## ✅ Step 8: 公開確認（別プロジェクトで）

```bash
npm install softbase/string-sanitizer
```

```ts
import { sanitize } from 'string-sanitizer';

console.log(sanitize('<p>Hello!@#</p>')); // "Hello"
```

---

## ✅ Step 9: TypeDoc で API ドキュメントを自動生成

### インストール

```bash
npm install --save-dev typedoc
```

### `typedoc.json` を作成

```json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeProtected": true
}
```

### スクリプト追加

```json
"scripts": {
  "build": "tsc",
  "docs": "typedoc"
}
```

### ドキュメント生成

```bash
npm run docs
```

> 📢 GitHub Pagesでホスティングする場合、`docs/` フォルダを使えば自動反映可能です。

---

## ✅ Step 10: GitHub Actions で CI/CD 自動化

### GitHub Secrets に追加

| 名前          | 用途                 |
| ----------- | ------------------ |
| `NPM_TOKEN` | npm publish 用トークン  |
| `GH_TOKEN`  | GitHub Pages 用（任意） |

👉 NPMトークン発行：[https://www.npmjs.com/settings/tokens](https://www.npmjs.com/settings/tokens)

### `.github/workflows/publish.yml` の作成

```yaml
name: Build and Publish

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org/'
      - run: npm ci
      - run: npm run build
      - run: npm run docs
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

### 自動公開の流れ

```bash
git tag v1.0.0
git push origin v1.0.0
```

---

## 📁 最終構成

```
string-sanitizer/
├── dist/
│   ├── index.d.ts
│   └── index.js
├── docs/
│   └── index.html（TypeDoc 出力）
├── src/
│   └── index.ts
├── .github/workflows/publish.yml
├── package.json
├── tsconfig.json
├── typedoc.json
├── README.md
```

---

## ✅ まとめ

`string-sanitizer` の開発から公開、APIドキュメント生成、GitHub Actions によるCI/CDまでを構築することで、誰でもプロフェッショナルな開発体験が可能になります。

---

## 🔗 ソースコード

* 📦 NPM: [`@softbase/string-sanitizer`](https://www.npmjs.com/package/@softbase/string-sanitizer)
* 🛠 GitHub: [https://github.com/softjapan/string-sanitizer](https://github.com/softjapan/string-sanitizer)