@katsu996/common-utils

TypeScriptプロジェクト向けの共通ユーティリティ関数と厳格な開発設定のコレクションです。

注意: このパッケージは個人用として作成されており、個人の開発スタイルや設定に最適化されています。

インストール

pnpm add @katsu996/common-utils

使用方法

プロジェクト設定の初期化・更新

パッケージがインストール済みの場合：

pnpm katsu-config

パッケージが未インストールの場合：

pnpm dlx katsu-config

新規プロジェクト（package.json未検出）の場合：

1. プロジェクト名の入力

   • プロジェクト名は英数字、ハイフン、アンダースコアのみ使用可能
   • 必須入力項目として検証

2. 設定ファイル選択

   • デフォルトで全ての設定ファイルが選択状態
   • 複数選択可能（Space キーで選択/解除）

3. 設定完了後の推奨コマンド

   pnpm install
   pnpm dev

既存プロジェクト（package.json検出）の場合：

• 現在の設定ファイル状況を表示
• 更新・追加する設定ファイルを選択

作成される設定ファイル：

• biome.jsonc - 厳格なリント・フォーマット設定
• tsconfig.json - 厳格なTypeScript設定
• mise.toml - Node.jsとpnpmのバージョン管理設定
• vite.config.ts - Viteビルド設定（ベース継承）
• vitest.config.ts - Vitestテスト設定（ベース継承）

ユーティリティ関数

基本的な使用例

import { add, sub } from "@katsu996/common-utils";

// 数値の加算
const sum = add(5, 3); // 8
const negativeSum = add(-2, -3); // -5
const decimalSum = add(1.5, 2.3); // 3.8

// 数値の減算
const diff = sub(10, 4); // 6
const negativeDiff = sub(-5, -3); // -2
const decimalDiff = sub(3.8, 1.5); // 2.3

型定義の使用例

import { CommonData } from "@katsu996/common-utils";

const user: CommonData = {
  id: "123",
  name: "John Doe"
};

数学関数のみをインポート

import { add, sub } from "@katsu996/common-utils/math";

const result = add(10, 20); // 30

設定ファイル

Biome設定(biome.jsonc)

{
  "extends": ["@katsu996/common-utils/biome"]
}

TypeScript設定(tsconfig.json)

{
  "extends": "@katsu996/common-utils/tsconfig"
}

Mise設定(mise.toml)

[tools]
node = "22.16.0"
pnpm = "10.12.4"

Vite設定(vite.config.ts)

import baseConfig from "@katsu996/common-utils/vite";
import { defineConfig, mergeConfig } from "vite";

export default mergeConfig(baseConfig, defineConfig({
  // プロジェクト固有の設定をここに追加
}));

Vitest設定(vitest.config.ts)

import baseConfig from "@katsu996/common-utils/vitest";
import { defineConfig, mergeConfig } from "vitest/config";

export default mergeConfig(baseConfig, defineConfig({
  // プロジェクト固有の設定をここに追加
}));

エクスポート

このパッケージは以下のパスでアクセス可能です：

| パス | 説明 | |------|------| | @katsu996/common-utils | メインユーティリティ関数 | | @katsu996/common-utils/math | 数学関数 | | @katsu996/common-utils/biome | Biome設定ファイル | | @katsu996/common-utils/tsconfig | TypeScript設定ファイル | | @katsu996/common-utils/vite | Viteベース設定 | | @katsu996/common-utils/vitest | Vitestベース設定 |

よくある質問（FAQ）

Q: katsu-configコマンドが実行できない

A: 以下の方法を試してください：

1. パッケージがインストールされている場合：

   pnpm katsu-config

2. パッケージがインストールされていない場合：

   pnpm dlx katsu-config

3. Windows環境の場合、PowerShellまたはコマンドプロンプトを使用してください。

Q: 設定ファイルを個別に更新したい

A: katsu-configコマンドを実行すると、既存プロジェクトでは現在の設定ファイル状況が表示され、更新・追加するファイルを選択できます。

Q: 既存の設定ファイルは上書きされますか？

A: はい、選択した設定ファイルは上書きされます。カスタマイズした設定がある場合は、事前にバックアップを取ることを推奨します。

Q: どのバージョンのNode.jsが必要ですか？

A: Node.js >= 22.16.0 が必要です。Mise設定ファイルでバージョンが指定されています。

トラブルシューティング

依存関係のインストールエラー

# キャッシュをクリアして再インストール
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript型エラー

# distディレクトリを削除して再ビルド
rm -rf dist
pnpm build
pnpm type-check

Biomeリントエラー

# 自動修正を試行
pnpm lint:fix
pnpm format

katsu-configが設定ファイルを作成しない

1. 実行時のディレクトリに書き込み権限があるか確認
2. package.jsonが正しく検出されているか確認
3. エラーメッセージを確認し、手動でインストールコマンドを実行

Viteプロジェクトの作成に失敗する

1. pnpmが正しくインストールされているか確認：pnpm --version
2. ネットワーク接続を確認
3. 手動でプロジェクトを作成：pnpm create vite

ベストプラクティス

設定ファイルの管理

• プロジェクト固有の設定が必要な場合、ベース設定を継承した後、必要な部分のみ上書きしてください
• チーム全体で同じ設定を使用する場合、このパッケージの設定を推奨します

ユーティリティ関数の使用

• 基本的な数学演算はaddとsub関数を使用してください
• より複雑な計算が必要な場合は、プロジェクト固有の関数として実装してください
• 型安全性を保つため、TypeScriptの型チェックを有効にしてください

開発ワークフロー

1. 新規プロジェクト開始時：

   pnpm katsu-config  # 設定ファイルの初期化
   pnpm install       # 依存関係のインストール

2. コード品質チェック：

   pnpm check         # 型チェック + リント
   pnpm test          # テスト実行

3. コミット前：

   pnpm format        # コードフォーマット
   pnpm check         # 品質チェック

セキュリティ

• 定期的に依存関係の脆弱性をチェック：pnpm audit
• 依存関係を最新の状態に保つ
• セキュリティアップデートがある場合は速やかに適用

開発者向け情報

開発に関する詳細は DEVELOPMENT.md を参照してください。

ライセンス

MIT License