nodejs-project-bootstrap

name	nodejs-project-bootstrap
description	Node.jsプロジェクトを新規作成する手順。

Node.js Project Bootstrap

基本手順

1. mise で使用バージョンを確認する。

mise latest node@lts
mise latest pnpm@latest

2. .tool-versions に Node.js の具体的バージョンを書く。

• lts や latest は書かない。
• 形式:

node <lts-version>

3. mise で Node.js をインストールする。

mise install

4. package.json を作る。

• type: "module" を必須にする。
• packageManager に pnpm の具体的バージョンを書く。
• version は通常 0.1.0 から始める。ワークスペースルートでは省略可。
• 公開しないプロジェクトは private: true を付与する。
• テンプレート:

{
  "name": "<name>",
  "version": "0.1.0",
  "type": "module",
  "description": "<description>",
  "author": "NISHIZAWA Shuntaro <[e-mail]>",
  "license": "MIT",
  "private": true,
  "packageManager": "pnpm@<latest-version>"
}

5. pnpm-workspace.yaml を作り、セキュリティ設定を有効化する。

minimumReleaseAge: 1440
saveExact: true
strictDepBuilds: true
trustPolicy: no-downgrade
trustPolicyIgnoreAfter: 10080

• 依存追加運用と ERR_PNPM_IGNORED_BUILDS の対応は pnpm-dependency-ops スキルを参照する。

TypeScript 導入ルール

• Node.js プロジェクトでは、ツール制約で不可能な設定ファイルを除き TypeScript を使う。
• tsconfig.json は手書きでオプションを埋めず、必ず @tsconfig/* を extends で利用する。
• 型チェックは厳格運用を前提にし、@tsconfig/strictest を併用する。
• ただし、exactOptionalPropertyTypes は false に、 verbatimModuleSyntax は true にする。

1. TypeScript 関連の依存を追加する。

• Node.js プロジェクト:

pnpm add -D typescript @tsconfig/node-lts @tsconfig/strictest

• Vite + React プロジェクト:

pnpm add -D typescript @tsconfig/vite-react @tsconfig/strictest

2. tsconfig.json は extends で構成する。

• Node.js プロジェクト例:

Node.jsプロジェクトの場合は moduleResolution を bundler にする。

{
  "extends": [
    "@tsconfig/node-lts/tsconfig.json",
    "@tsconfig/strictest/tsconfig.json"
  ],
  "compilerOptions": {
    "exactOptionalPropertyTypes": false,
    "verbatimModuleSyntax": true,
    "moduleResolution": "bundler"
  }
}

• Vite + React プロジェクト例:

{
  "extends": [
    "@tsconfig/vite-react/tsconfig.json",
    "@tsconfig/strictest/tsconfig.json"
  ],
  "compilerOptions": {
    "exactOptionalPropertyTypes": false,
    "verbatimModuleSyntax": true
  }
}

• 追加オプションが必要な場合のみ、最小限の項目を上書きする。

3. package.json に型チェック用スクリプトを追加する。

{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}

• ビルドツールとして tsc を使わない。ビルドする場合は tsdown を使うこと。
• tsdown ガイド: https://tsdown.dev/guide/
• @tsconfig/* の一覧と使い分け: https://github.com/tsconfig/bases/blob/main/README.md

Linter / Formatter 導入ルール

• 重要: Linter と Formatter は必ず導入し、oxlint と oxfmt を使う。
• 基本はデフォルト設定で運用する。
• oxlint は type-aware linting を有効化する。
• type-aware linting のために oxlint-tsgolint を必ず導入する。

1. 依存を追加する。

pnpm add -D oxlint oxlint-tsgolint oxfmt

2. 設定ファイルを生成する。

pnpm exec oxlint --init
pnpm exec oxfmt --init

3. package.json の scripts に実行コマンドを追加する。

{
  "scripts": {
    "format": "oxfmt",
    "format:check": "oxfmt --check",
    "lint": "oxlint",
    "lint:fix": "oxlint --fix"
  }
}

4. oxlint のデフォルト設定に type-aware linting を、 oxfmt のデフォルト設定に import sort と package.json の scripts sort を追加する。

.oxlintrc.json:

{
  "options": {
    "typeAware": true
  }
}

.oxfmtrc.json:

{
  "experimentalSortImports": {
    "groups": ["builtin", "external", "internal", "parent", "sibling", "index"]
  },
  "experimentalSortPackageJson": {
    "sortScripts": true
  }
}

5. 詳細設定は公式ドキュメントを参照する。

• oxlint type-aware linting: https://oxc.rs/docs/guide/usage/linter/type-aware
• oxfmt config file reference: https://oxc.rs/docs/guide/usage/formatter/config-file-reference

注意

• Node.js の固定は .tool-versions で行う。mise.toml は使わない。
• pnpm の固定は .tool-versions ではなく package.json の packageManager で行う。
• pnpm create は使用しないこと。テンプレートではなく自分でプロジェクトを作成する。