Typings の 使い方

Typings で よく使う 基本的なコマンド についてまとめてみました。

目次

基本操作

定義のインストール

typings/ ディレクトリ配下に型定義情報を書き込みます。

typings install [<ソース>~]<パッケージ名> [--global] [--save]
ソース
型定義が保存されているデータソースを指定します。 指定できるデータソースは後述の「利用可能なソース」を参照してください。
パッケージ名
インストールしたい型定義の名前を入力します。 どのような型定義が利用可能かは、後述の「定義の検索」を参考にして探します。

例えば、 node の型定義をインストールする場合、以下のようなコマンドを実行します。

typings install dt~node --global --save

定義のアンインストール

typings/ ディレクトリから型定義情報を削除します。

typings uninstall <パッケージ名> [--global] [--save]
パッケージ名
インストール済みの型定義名を入力します。

例えば、 node の型定義をアンインストールする場合、以下のようなコマンドを実行します。

typings uninstall node --global --save

定義の検索

Typingsレジストリから依存情報を検索します。

typings search [[--name] <パッケージ名>] [[--source] <ソース>]
パッケージ名
検索したい型定義名の一部を入力します。
ソース
検索先のデータソースを指定します。 指定できるデータソースは後述の「利用可能なソース」を参照してください。

「angular」の文字列を含むの型定義を探す場合、以下のようなコマンドを実行します。

typings search angular

インストール済み定義の一覧表示

インストール済みの型定義情報を一覧表示します。

typings list 

おまけ

利用可能なソース

ソース名 説明
npm NPMから検索します。
github GitHubから検索します。
bitbucket Bitbucketから検索します。
bouwer Bowerから検索します。
common "source"以外の標準ライブラリから検索します。
shared 共有ライブラリ機能。
lib 「shared」と同じ。
env atomelectron といった環境。 --global でインストールします。
global グローバルライブラリ(window.<var>--global でインストールします。
dt DefinitelyTyped から探します。 ほとんどのライブラリで --global でインストールします。

よく使うライブラリの型定義

  ライブラリ パッケージ名 ソース ホームページ
Node.js node dt http://nodejs.org/
Express express dt http://expressjs.com
AngularJS angular dt http://angularjs.org
jQuery jquery dt http://jquery.com/
React.js react dt http://facebook.github.io/react/
Underscore.js underscore dt http://underscorejs.org/
Backbone.js backbone dt http://backbonejs.org/

上記でチェックしたものをまとめてインストールする

typings install dt~node dt~express dt~jquery --global --save

参考記事

Typings の インストール


目次


Typings とは

Typings は TypeScript の 型定義ファイル 管理ツールです。

Typings では typings.json を利用して型定義ファイルのソースを判断します。

Visual Studio Code において、インテリセンスが TypeScript の 型定義ファイル ( d.ts ファイル ) を利用しているので、 Visual Studio Code の インテリセンス に何を使うかは 間接的に Typings で制御することになります。

インストール

ここでは npm を利用してインストールを行います。 npm がまだインストールされていない場合、 こちら を参考にしてインストールを行ってください。

  1. npm install typings --global を実行

  2. インストールが始まるのでしばらく待ちます…

  3. インストール完了

動作確認

動作確認は typings --version でインストールバージョンを確認してみます。

正しくインストールされていればインストールバージョンが表示されます。

参考記事

Visual Studio Code に Node.js と Express の インテリセンス を 追加 する

Visual Studio Code で Node.js アプリケーション開発 を行う際、やはり インテリセンス が使いたいものです。 …が、標準だと インテリセンス が入っていません。

この記事では Visual Studio Code に Node.js および Express の インテリセンス 機能を追加して インテリセンス を 有効化 させる方法をまとめます。


目次


Visual Studio Code の インテリセンス

Visual Studio Code では TypeScript 向けの型定義ファイル (例えば node.d.ts ) を使ってインテリセンスを実現しているようです。 なので、 d.ts ファイル (DefinitelyTyped) を必要に応じてインストールすることで Node.js, Express に限らず さまざまな インテリセンスを実現できます。

この 型定義ファイルを管理するツールに 「Typings」 と呼ばれるツールがあり、 npm を利用してインストールすることができます。 「Typings」はいわゆる 「DefinitelyTyped の パッケージ管理ツール」 になります。

以下の手順では Typings をインストールして、 Node.js と Express の型定義ファイルを導入しています。

インストール 手順

まず前提として「すでに Node.js / npm がインストール済みである」ものとします。 まだ Node.js / npm を インストール していなければ こちら を参考にインストールしてください。

  1. typings を インストール
    npm install typings --global
    
  2. プロジェクトディレクトリ へ 移動(以下は C:\workspace\testproject へ移動する例)
    cd C:\workspace\testproject
    
  3. Node.js および Express の 定義ファイル を インストール
    typings install dt~node --global --save
    typings install dt~express dt~serve-static dt~express-serve-static-core --global --save
    

Typings がインストールする先は カレントディレクトリ になるので、プロジェクトルートディレクトリへ移動しておく必要があります。 --global と指定しながらも カレントディレクトリ 配下 に typings フォルダ が作成され、その下にすべて保存されます。 なので、インテリセンス有効化したいプロジェクトのルートディレクトリへ移動してから上記操作をする必要があります。

インテリセンス の 動作確認

Visual Studio Code を再起動して適当な JavaScript ファイルを作成してみます。 以下の図のように 入力途中 または . を入力した際プルダウンが出ていれば正常動作しています。

参考記事

Visual Studio Code の インストール

Visual Studio Code をインストールする手順をまとめます。 基本的にはダウンロードしてそのままインストールすれば動きます。 インストール時のオプションで気にする点などはメモしてありますので、参考にしてください。

目次

ダウンロード

  1. Visual Studio Code のサイトへアクセス

    Download Visual Studio Code

  2. 「Download for Windows」を選択してダウンロード

インストール

  1. 「次へ」を選択

  2. 「同意する」を選択して、「次へ」を選択

  3. インストール先を設定して、「次へ」を選択

    基本的にはデフォルト設定のままで問題ありません。

  4. スタートアップに作成するフォルダ名を指定して、「次へ」を選択

    分かりづらくなるのでよほどの理由がない限りはデフォルト設定のままにします。

  5. オプションを任意に選択して、「次へ」を選択

    「PATH への追加」は選択しておいた方が良いです。

  6. 内容を確認して、「インストール」を選択

  7. インストール中、しばらく待ちます…

  8. 「完了」を選択

  9. Visual Studio Code が起動します

各部の名称

Visual Studio Code を起動した基本画面の各部の名称および機能概略は以下の通りです。

ビューバー
左端に表示され、表示するコンテキスト(ファイル編集、検索、デバッグ等)を切り替えます。
サイドバー
開いたプロジェクトをエクスプローラーのようなレイアウトで表示します。
エディタ
ファイル編集するメインエリア。フィルは最大3ファイルまで開くことができます。
ステータスバー
開いているプロジェクトまたはファイルの情報を表示します。
パネル
標準出力、デバッグ情報、エラー、警告、ターミナルなど追加情報を表示します。

端末 の 起動

デフォルトだと「パネル」は表示されていません。 この部分に「端末」を表示したい場合、以下のどちらかの方法で起動できます。

  • Ctrl + @ の キーボードショートカット
  • メニューから [表示]-[統合ターミナル] を選択する

参考記事

Node.js + Express で エラーページ を カスタマイズ する 方法

Node.js + Express (ejsテンプレート) の環境において 404エラーページ と 500エラーページ を カスタムエラーページ にする方法をまとめます。 大きくは「エラー処理の実装」と「エラーページの実装」の2点を行います。 以下ではそれぞれについて詳しく見ていきます。

目次

概要

すべてのファイルを列挙しているわけではありませんが、前提となる主要なフォルダおよびファイルについて列挙します。 想定は以下のような環境です。

プロジェクト構成

PROJECT_ROOT
├ node_modules
│  └ …
├ public
│  └ …
├ routes
│  └ home.js
├ views
│  ├ home
│  │  └ index.js
│  ├ 404.ejs
│  └ 500.ejs
└ app.js

今回作成するのは エラー処理の実装箇所として app.ja、 エラーページの実装として 404.ejs および 500.ejs を作成します。 テンプレートエンジンに "ejs" を利用しているので、エラーページの拡張子も "ejs" です。

エラー処理 の 実装

app.js

var express = require('express');
var fs = require('fs');

// express の実態 Application を生成
var app = express();

// テンプレートエンジンを EJS に設定
app.set('views', './views');
app.set('view engine', 'ejs');

// ルーティング設定
var files = fs.readdirSync('./routes');
for(var file of files){
    app.use('/', require('./routes/' + file));
}

// カスタムエラーページ
app.use(function (request, response, next) {
    // 出力するデータ
    var data = {
        method: request.method,
        protocol: request.protocol,
        version: request.httpVersion,
        url: request.url
    };

    // エラーを返却
    response.status(404);
    if (request.xhr) {
        response.json(data);
    } else {
        response.render('./404', { data: data });
    }
});
app.use(function (error, request, response, next) {
    // 出力するデータ
    var data = {
        method: request.method,
        protocol: request.protocol,
        version: request.httpVersion,
        url: request.url,
        name: error.name,
        message: error.message,
        stack: error.stack
    };

    response.status(500);
    if (request.xhr) {
        response.json(data);
    } else {
        response.render('./500', { data: data });
    }
});

// サーバーをポート 3000 で起動
app.listen(3000);

404エラー も 500エラー も app.use を利用しますが、引数となる関数が異なります。 両者に共通するのは app.js の中でできるだけ最後の app.use で記載するようにします。 (上記の例だとルーティング設定よりも後に登録する) app.use は上から順に登録および処理がされるので、エラー処理はできるだけ最後に行うよう設定します。

404エラーの場合、 function (request, response, next) の 3引数 を持つ関数を引数に与えます。 エラーページを返す際、ステータスに 404 を設定して response.render で返却します。

500エラーの場合、 function (error, request, response, next) の 4引数 を持つ関数を引数に与えます。 最初の引数は エラーオブジェクト で、エラー名やメッセージ、スタックトレースが含まれています。 エラーページを返す際、400エラーと同様に、ステータスに 500 を設定して response.render で返却します。

エラーページ の 実装

ページにあまりひねりはありません…単純に必要な情報を表示しています。 ただし、500エラーは開発を想定してエラー名、メッセージ、スタックトレースを出していますが、本番ではこのような情報が出ないようくれぐれも注意してください。

404.ejs

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>404 ERROR</title>
    <link rel="icon" href="/public/images/favicon.ico" />
    <link rel="stylesheet" href="/public/third_party/bootstrap/dist/css/bootstrap.css" />
    <link rel="stylesheet" href="/public/stylesheets/index.css" />
    <script type="text/javascript" src="/public/third_party/jquery/dist/jquery.js" defer></script>
    <script type="text/javascript" src="/public/third_party/bootstrap/dist/js/bootstrap.js" defer></script>
  </head>
  <body>
    <div class="container">
      <h1>404 : Not Found</h1>
      <h2>リクエスト</h2>
      <table class="table table-bordered">
        <tr>
          <th class="col-md-2">request</th>
          <td class="col-md-10">
            <span><%= data.method %></span>
            <span> </span>
            <span><%= data.url %></span>
            <span> </span>
            <span><%= (data.protocol || "").toUpperCase() %>/<%= data.version %></span>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>

500.ejs

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>500 ERROR</title>
    <link rel="icon" href="/public/images/favicon.ico" />
    <link rel="stylesheet" href="/public/third_party/bootstrap/dist/css/bootstrap.css" />
    <link rel="stylesheet" href="/public/stylesheets/index.css" />
    <script type="text/javascript" src="/public/third_party/jquery/dist/jquery.js" defer></script>
    <script type="text/javascript" src="/public/third_party/bootstrap/dist/js/bootstrap.js" defer></script>
  </head>
  <body>
    <div class="container">
      <h1>500 : Internal Server Error</h1>
      <h2>リクエスト</h2>
      <table class="table table-bordered">
        <tr>
          <th class="col-md-2">request</th>
          <td class="col-md-10">
            <span><%= data.method %></span>
            <span> </span>
            <span><%= data.url %></span>
            <span> </span>
            <span><%= (data.protocol || "").toUpperCase() %>/<%= data.version %></span>
          </td>
        </tr>
      </table>
      <h2>エラー</h2>
      <table class="table table-bordered">
        <tr>
          <th class="col-md-2">name</th>
          <td class="col-md-10"><%= data.name %></td>
        </tr>
        <tr>
          <th>message</th>
          <td><%= data.message %></td>
        </tr>
        <tr>
          <th>stack</th>
          <td><%= data.stack %></td>
        </tr>
      </table>
    </div>
  </body>
</html>

以上が Node.js + Express (ejsテンプレート) でカスタムエラーページを作成する方法です。 これでデフォルトのしょぼいページからは脱却できるはハズ!!

Node.js で module を 作成 および 利用 する 方法

開発をしているとよく使う機能や関数、値などはモジュール化して掃き出しておきたいことがあると思います。 Node.js では module を使うことでそうしたことが実現できます。 ここでは、 module の具体的な作成方法と利用方法についてまとめます。


目次


基本的な使い方

module の 作成

module は 1ファイル として切り出して作成します。 作成したファイルにおいて module.exports にモジュール化したいオブジェクトや関数を設定することで module が作成できます。

module.js

var say = function () {
  console.log('hello');
};
module.exports = say;

module の 利用

require でモジュールファイルを指定すると module.exports に設定されたオブジェクトや関数が取り出せます。 現在のJavaScriptから見た相対パスを指定します。

program.js

var say = require('./module.js');
say();

サンプルコード

以下ではサンプルコードを見ながら具体的な使い方を見ていきます。 といっても「利用するときは require("パス") で呼び出し」 「作成するときは exports または module.exports に設定」を行うだけです。

複数メソッドのモジュール化

単純に作成した複数メソッドをモジュール化する例を以下に載せます。 複数のオブジェクトやメソッドを1つのモジュールにする場合、 exports の プロパティ を増やして追加することで出力ができます。

foo.js

var circle = require("./circle.js");
console.log(`半径 4 の 円の面積 は ${circle.area(4)}`);

circle.js

const PI = Math.PI;

exports.area = function (r) {
    return PI * r * r;
}

exports.circumference = function (r) {
    return 2 * PI * r;
}

この例で var circle = require("./circle.js") すると foo.js で以下のような コード を実行するのと同じ意味になります。

var circle = {
    "area": function (r) {
        return PI * r * r;
    },
    "circumference": function (r) {
        return 2 * r * PI;
    }
};

単一オブジェクトのモジュール化

単一のメソッドやクラスを出力する場合、 module.exports に対して出力したいメソッドやクラスを設定します。 先の例であげた exports に設定しても出力できません。

foo.js

var Square = require("./square.js");
var o = new Squre(2);
console.log(`1辺 が 2 の 正方形の面積 は ${o.area()}`);

square.js

var Square = function (width) {
    this.width = width;
};

Square.prototype.area = function () {
    return this.width * this.width;
};

module.exports = Square;

この例の場合、 foo.js で実行している var Square = require("./square.js") は以下のコードと同等になります。

var Square = function (width) {
    this.width = width;
};

Square.prototype.area = function () {
    return this.width * this.width;
};

[補足] module の 読み込み

読み込み順

パス Y にあるモジュールで require(X) を行った場合、以下のような読み込みを行います。

パス Y にあるモジュールで require(X) を実行

  1. X がコアモジュールの場合
    1. コアモジュールを返します
    2. 終了
  2. X.//../ で始まる場合
    1. LOAD_AS_FILE(Y + X)
    2. LOAD_AS_DIRECTORY(Y + X)
  3. LOAD_NODE_MODULES(X, dirname(Y))
  4. "not found" の例外をスロー

LOAD_AS_FILE(X)

  1. X がファイルの場合、 JavaScript テキスト として X を読み込んで終了
  2. X.js がファイルの場合、 JavaScript テキスト として X.js を読み込んで終了
  3. X.json がファイルの場合、 JavaScript オブジェクト として X.json を読み込んで終了
  4. X.node がファイルの場合、 バイナリアドオン として X.node を読み込んで終了

LOAD_AS_DIRECTORY(X)

  1. X/package.json がファイルの場合
    1. X/parse.json をパースし、mainフィールドの値を確認
    2. LOAD_AS_FILE( X/mainフィールドに指定されたファイル )
  2. X/index.js がファイルの場合、X/index.js を JavaScript として読み込んで終了
  3. X/index.json がファイルの場合、X/index.json を JavaScript として読み込んで終了
  4. X/index.node がファイルの場合、X/index.node を JavaScript として読み込んで終了

LOAD_NODE_MODULES(X, START)

  1. let DIRS = NODE_MODULES_PATHS(START)
  2. for each DIR in DIRS
    1. LOAD_AS_FILE( DIR/X )
    2. LOAD_AS_DIRECTORY( DIR/X )

NODE_MODULES_PATHS(START)

  1. let PARTS = path split(START)
  2. let I = count of PARTS - 1
  3. let DIRS = []
  4. while I >= 0,
    1. PARTS[I] が "node_modules" の場合、CONTINUE
    2. DIR = path join(PARTS[0 .. I] + "node_modules")
    3. DIRS = DIRS + DIR
    4. let I = I - 1
  5. return DIRS

キャッシュ

一度読み込まれたモジュールファイルはキャッシュされます。 複数回同じモジュールファイルを読み込もうとしても最初に読み込んだファイルのキャッシュを利用するので複数回読み込むことはありません。

参考記事

package.json の 仕様 (日本語)

( この記事は package.json - Specifics of npm's package.json handling をベースに作成しています。 package.json を作成する際、その 書き方 の 参考 になればと思います。 )

このドキュメントは pakage.json に何を書くべきか について記載しています。 package.json は単に JavaScript オブジェクトリテラルであるだけでなく JSON でなければなりません。

このドキュメントに記載した動作の多くは npm-config に記載された設定の影響を受けます。

{
  "name": "blue-leaf",
  "description": "Physics-like animations for pretty particles",
  "main": [
    "js/motion.js",
    "sass/motion.scss"
  ],
  "dependencies": {
    "get-size": "~1.2.2",
    "eventEmitter": "~4.2.11"
  },
  "devDependencies": {
    "qunit": "~1.16.0"
  },
  "moduleType": [
    "amd",
    "globals",
    "node"
  ],
  "keywords": [
    "motion",
    "physics",
    "particles"
  ],
  "authors": [
    "Betty Beta <bbeta@example.com>"
  ],
  "license": "MIT",
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "test",
    "tests"
  ],
  "homepage": "http://betty.github.io/blue-leaf/index.html",
  "repository": {
   "type": "git",
    "url": "git://github.com/betty/blue-leaf.git"
  },
  "resolutions": {
    "angular": "1.3.0-beta.16"
  },
  "private": true
}
プロパティ名 説明
name string

必須

package.json にとって name と version はもっとも重要なフィールドです。 これらは必須項目で、これらが指定されていないと パッケージ をインストールできません。 name と version の組み合わせでパッケージを一意に特定します。 パッケージの変更は version の変更も伴うべきものです。

ルール:

  • 214文字以下でなければなりません。この文字数にはスコープ文字列も含まれます。
  • ドット . または アンダースコア _ から始めることはできません。
  • 新しいパッケージ名には大文字を含んではいけません。
  • nameフィールドは URL、コマンドライン引数、フォルダ名の一部になります。そのため、安全でないURL文字を含められません。

ヒント:

  • Nodeコアモジュールと同じ名前を使ってはいけません。
  • "js"や"node"を名前の中に含んではいけません。package.json を記載している時点で js であり、 "engine" フィールドを利用することで エンジン を特定することができます。
  • nameフィールドは require() の引数に渡されるので、ある程度短くも説明的であるべきです。
  • 使おうとしている名前がすでに使われているかどうか、npmレジストリを調べてみてください。
    https://www.npmjs.com/
version string

必須

version は npm の依存として含まれている node-semver で構文解析可能でなければなりません。

バージョン番号に関する詳細は semver を参照してください。

description string 説明を記載します。 作成するパッケージを、npm search でリストする際、探しやすくします。
keywords string[] キーワードを文字配列で記載します。 作成するパッケージを、npm search でリストする際、探しやすくします。
homepage string

プロジェクトホームページへのURL。

注意:

"homepage" は "url"とは異なりませ宇。 もし "url" フィールドを設定する場合、レジストリはパッケージが別の場所に移されたのでリダイレクトしようとします。

bugs object

バグトラッカーへの URL または / かつ バグ連絡先となる メールアドレス。 これらの値はパッケージ利用者がバグに遭遇したときに役立ちます。

サンプル:

{
  "url": "https://github.com/owner/project/issues",
  "email": "project@hostname.com"
}

"url" と "email" のどちらか片方または両方を指定することができます。 もし URL のみを指定する場合、"bugs"フィールドの値は単純文字列で指定できます。

URL が指定されている場合、npm bugs コマンドで使われます。

license string

パッケージ利用における許諾や制限が分かるよう、ライセンスを記載します。

BSD-2-Clause や MIT といった一般的なライセンスを用いる場合、 SPDXライセンス識別子 を指定します。

サンプル:

{
  "license": "BSD-3-Clause"
}

SPDXライセンス識別子は こちら を参照してください。 理想的には OSI 承認されたものを利用してください。

複数ライセンスを適用する場合、SPDXライセンス構文に従って記載してください。

サンプル:

{
  "license": "(ISC OR GPL-3.0)"
}

SPDXライセンス識別子を利用せず独自のライセンスを使う場合、以下のような文字列値を指定します。

{
  "license": "SEE LICENSE IN <filename>"
}

filename に指定されるファイルはパッケージのトップレベルに配置してください。

author / conributors string / object / string[] / object[]

"author" は1人、 "contributors" は 複数人です。 人を表現するオブジェクトは "name" フィールドとオプションで "url" と "email" を持ちます。

サンプル:

{
  "name": "Barney Rubble",
  "email": "barney@rubble.com",
  "url": "http://barnyrubble.tumblr.com/"
}

これらを短くした単一文字列表現も利用できます。

サンプル:

"Barney Rubble <Barney@rubble.com> (http://barneyrubble.tumblr.com/)"

"email" と "url" のどちらもオプションです。

files string[]

プロジェクトに含まれるファイルリストを指定します。 もしフォルダー名のリストを指定する場合、フォルダーにあるファイルが含まれます。 (ただし、他のルールは無視されます)

パッケージのルートディレクトリまたはサブディレクトリに ".npmignore"ファイル を配置することができます。 これは ".npmignore" はちょうど ".gitignore" のような動きをします。

以下のファイルは設定に関わらず常に含まれます。

  • package.json
  • README
  • CHANGELOG
  • LICENSE / LICENCE

以下のファイルは常に無視されます。

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • *.swp
  • .DS_Store
  • ._*
  • npm-debug.log
main string

パッケージのエントリーポイントを指定します。 foo というパッケージを作成して、ユーザーがインストールし、require("foo") を実行すると、 mainモジュールで出力設定されたオブジェクトが返されます。

パッケージフォルダのルートからの相対パスで指定します。

多くのモジュールにおいてメインスクリプトを指定すると考えると分かりやすいです。

bin object

多くのパッケージにおいて PATH に実行可能なファイルをインストールしたいという場合があります。 npm では簡単に設定できます。

利用するには、コマンド名からローカルファイル名へのマッピング情報を package.json の binフィールドに設定します。 インストールするとき、グローバルインストールの場合シンボリックリンクを prefix/bin に、ローカルインストールの場合 ./node_modules/.bin/ に配置します。

例えば myapp を以下のように設定した場合、

"bin": {
  "myapp": "./cli.js"
}

myapp をインストールすると、 cli.js スクリプトへのシンボリックリンクを /usr/local/bin/myapp へ作成します。

もし単一の実行可能ファイルでパッケージ名と同じ名前の場合、単純な文字列で表記することができます。

サンプル(以下の2つは同じです):

"bin": {
  "name": "my-program",
  "version": "1.2.5",
  "bin": "./path/to/program"
}
"bin": {
  "name": "my-program",
  "version": "1.2.5",
  "bin": {
    "my-program": "./path/to/program"
  }
}
man string / string[]

man プログラム向けに単一ファイルかファイル名の配列を指定します。

単一ファイルを指定する場合、指定したファイル名に関わらず man <パッケージ名> で呼び出せます。

例えば以下のような設定をした場合、 ./man/doc.1 というファイルは man foo コマンドで呼び出されます。

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": "./man/doc.1"
}

ファイル名がパッケージ名で始まっていない場合、プレフィックスにパッケージ名が付きます。 例えば以下のような設定をした場合、man foo および man foo-bar が作られます。

{
  "name": "foo",
  "version": "1.2.3",
  "description": "A packaged foo fooer for fooing foos",
  "main": "foo.js",
  "man": ["./man/foo.1", "./man/bar.1"]
}

manファイルのファイル名は数値で終わっている必要があります。 オプションで、圧縮している場合は .gz サフィックスが付けられます。 数値はセクションを示しており、以下のような設定をした場合、 man foo および man 2 foo が作られます。

directories object

"doc"、"lib"、"man"といったディレクトリがどこにあるかを定義できます。

lib

ライブラリファイル郡がどこにあるかを定義します。

bin

"bin"を定義する場合、すべてのファイルを定義したフォルダ配下に配置します。

"bin"と"directories.bin"の両方を定義するとエラーになります。 単一ファイルを定義する場合は"bin"を利用し、存在するすべてのファイルを定義する場合は"directories.bin"を利用します。

man

定義されたディレクトリ配下のデータを元に manページ を作成します。 "man"へのショートカットになります。

doc

markdownファイルを配置します。 いつかどこかでうまく表示できるようになるハズ…。

example

サンプルスクリプトを配置します。 いつかどこかでうまく表示できるようになるハズ…。

例えば以下のような設定を記述します。

{
   "lib": "src/lib",
   "bin": "local/binaries",
   "doc": "doc" 
} 
repository object / string

コードがどこにあるかを定義します。コード修正に参加したいと思った人にとって有用な情報になります。 GitHub上にリポジトリがあれば npm docs コマンドで参照できます。

"repository": {
  "type" : "git",
  "url" : "https://github.com/npm/npm.git"
}
"repository": {
  "type" : "svn",
  "url" : "https://v8.googlecode.com/svn/trunk/"
}

URLは一般に公開されたURLを使用します。 また、htmlページではなく機械が読み取れるURLを指定します。

GitHub、GitHub gist、Bitbucket、GitLabリポジトリを利用する場合、ショートハンドが利用できます。

"repository": "npm/npm"
"repository": "gist:11081aaa281"
"repository": "bitbucket:example/repo"
"repository": "gitlab:another/repo"
scripts object

パッケージのライフサイクル中における様々なシーンで呼び出されるコマンドを定義します。 キーはライフサイクル中のイベント名で、値はコマンド実行されたときに実行するスクリプトを定義します。

以下は "install" および "uninstall" コマンドを定義するサンプルです。

"scripts" : {
  "install" : "scripts/install.js",
  "uninstall" : "scripts/uninstall.js"
}
config object

config オブジェクトではパッケージスクリプトで利用する設定値を指定できます。 例えば以下のような設定を行った場合、

{
  "name" : "foo",
  "config" : {
    "port" : "8080"
  }
}

npm_package_config_port という環境変数が設定されます。 この値は npm config set foo:port 8001 のように実行することで上書きすることもできます。

dependencies object

dependencies は単純なオブジェクトでパッケージ名とバージョン範囲を指定します。 バージョン範囲は1つ以上のスペース区切り文字列を指定します。 dependencies には tarball や git の URL を指定することもできます。

テスト用の依存ファイルは指定しないでください。 以下の devDependencies を参照してください。

バージョン番号に関する詳細は semver を参照してください。

version 指定されたバージョンのみ
>version 指定されたバージョンより新しいバージョン
>=version 指定されたバージョン以降の新しいバージョン
<version 指定されたバージョンより古いバージョン
<=version 指定されたバージョン以前の古いバージョン
~version ほぼ類似するバージョン。 パッチバージョンレベルで更新されたもの。 詳細は semver を参照してください。
^version 互換性のあるバージョン。 メジャーバージョンが更新されないレベルのもの。 詳細は semver を参照してください。
1.2.x 1.2.0, 1.2.1, ... 。1.3.0はNG。
http://... 以下の URL を参照してください。
* どのようなバージョンでも許可。
""(空文字) * と同じ。
version1 - version2 >=version1 <=version2 と同じ
range1 || range2 range1 または range2 を満たす場合を許可
git... 以下の Git URL を参照してください。
user/repo 以下の GitHub を参照してください。
tag npm-tab で指定されたタグを指定
path/path/path 以下の ローカルバス を参照してください。

サンプルは以下のようになります。

"dependencies" : {
  "foo" : "1.0.0 - 2.9999.9999",
  "bar" : ">=1.0.2 <2.1.2",
  "baz" : ">1.0.2 <=2.3.4",
  "boo" : "2.0.1",
  "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
  "asd" : "http://asdf.com/asdf.tar.gz",
  "til" : "~1.2",
  "elf" : "~1.2.3",
  "two" : "2.x",
  "thr" : "3.3.x",
  "lat" : "latest",
  "dyl" : "file:../dyl"
}

URL

tarball への URL を指定します。 指定された tarball はインストール時にダウンロードされます。

Git URL

Git URL は以下のように指定します。

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish には git checkout の引数で利用するタグ、sha、ブランチを指定できます。 デフォルトは master です。

GitHub URL

バージョン 1.1.65 以降では、"foo" : "user/foo-project" のように指定できます。 Git URL のように commit-ish サフィックスをふくめることもできます。

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

ローカルパス

バージョン 2.0.0 以降では、パッケージに含んでいるローカルディレクトリのパスを指定できます。 ローカルパスは npm install -S または npm install --save で保存できます。 保存する際は相対パスで package.json に保存されます。

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

この機能は外部サーバーへアクセスしたくない、ローカルオフライン開発やテスト実施においてnpmインストールが必要な時に便利です。 ただし、パッケージを一般公開する際は使わないようにしてください。

devDependencies object

公開されたパッケージを利用する際、テストフレームワークやドキュメントフレームワークといったものはダウンロードする必要がありません。 こうした場合、一番良いのはこれらを devDependencies に指定することです。

ここで指定したパッケージはパッケージルートで npm link または npm install を実行するとインストールされ、他のパラメータと同様に管理されます。 詳しくは npm-config を参照してください。

CoffeeScriptといったプラットフォーム固有でないビルドイベントは、devDependencies でパッケージ依存を指定して prepublish スクリプトを使うことで実現します。

サンプル:

{
  "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

prepublishスクリプト は公開前に実行されます。 そのため、ユーザーはコンパイルを気にすることなく機能を利用することができます。 開発モード(例えば、ローカルで npm install を実行する場合)、このスクリプトはうまく動作するため、簡単にテストができます。

peerDependencies object

場合により、ホストツールやライブラリとの互換性のため、必ずしも必要ではないパッケージがあるかもしれません。 これは一般にプラグインと呼ばれるものです。 特に、ホストドキュメントによって期待されるまたは指定される、特定のインターフェースを公開しているかもしれません。

サンプル:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

あなたのパッケージ tea-latte をインストールすることができるのはホストパッケージである tea がバージョン 2.x の場合のみとすることができます。 npm install tea-latte は以下の依存グラフの場合だけ実行できます。

├── tea-latte@1.3.5
└── tea@2.2.0

注意: npm のバージョンが 1 または 2 の場合、peerDependencies で指定されたバージョンより高ければ自動的にインストールを行います。 次のバージョン (バージョン 3) ではこのようなことが起こらなくなり、代わりに警告が表示されるようになります。 npm 1 と 2 のこの動作は頻繁に混乱を起こし依存地獄に陥れていましたが、できるだけ避けられるようにデザインされます。

他のプラグインをインストールしようとしたとき依存エラーを起こすことがあります。 この原因は、あなたのプラグインが要求する依存バージョンがパッチバージョンまで指定してしまっているためです。

ホストコンパイルを考えたとき、ホストパッケージのメジャーバージョンの変更のみがあなたのプラグインを壊します。 ですから、もしあなたがすべてのホストパッケージをバージョン 1.x で動作させたいなら、 ^1.0 または 1.x を指定します。 もし 1.5.2 で出てきた機能に依存しているのであれば >=1.5.2 <2 を指定します。

bundledDependencies string[]

パッケージ公開するときバンドルするパッケージの配列を指定します。

bundleDependencies の綴りでも動作します。

optionalDepencencies object

dependency を利用するがインストール時に失敗とさせたくない場合、 optionalDependencies を利用します。 これはパッケージ名とバージョンまたはURLのマップブジェクトで、dependencies に似ています。 違いはインストール時のエラーを発生させない点です。

インストールは行われるので、依存関係が欠損している部分をプログラムで処理s手あげる必要があります。 以下にサンプルコードを記載します。

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

optionalDependencies の値は dependencies で上書きされます。

engines object

動作するnodeバージョンを指定することができます。

"engines" : {
  "node" : ">=0.10.3 <0.12"
}

dependencies と同様に特に指定しないまたは "*" を指定した場合、どのnodeバージョンでも動作します。 engines はどのバージョンで正しく動作するかを指定します。

engine-strict フラグが設定されていなければ、この値は警告を表示するのみの動作になります。

engineStrict boolean

この機能は npm 3.0.0 で廃止されます。

npm 3.0.0 以降では engine-strict を指定するようにしてください。

os string[]

どの OS で動作するかを指定します。

"os": [
  "darwin", "linux"
]

! を使用することでブラックリスト指定もできます。

"os": [
  "!win32"
]

ブラックリストとホワイトリストは両方使えます。

cpu string[]

ある特定のCPUアーキテクチャで動作する場合、それを指定します。

"cpu": [
  "x64", "ia32"
]

ブラックリストも指定できます。

"cpu": [
  "!arm", "!mips"
]
preferGlobal boolean

あなたのパッケージがグローバルに利用されるコマンドラインアプリケーションである場合、この値を true にして ローカルインストールされた場合に警告表示するようにします。

private boolean

"private" : true を設定すると、npm は該当パッケージの公開を拒否します。

これは間違ってプライベートリポジトリが公開されるのを防ぐために使います。 もしパッケージを特定のレジストリにのみ公開したい場合は publishConfig を設定して registry 設定を公開するときに上書きする設定を行ってください。

publishConfig

公開時に利用される設定値を指定します。 タグ、レジストリ、アクセス先を指定すると、 特定のパッケージに "latest" のタグ付けがされていない、 グローバルに公開されたレジストリを使う、 デフォルトでプライベートなモジュールを見ている、といったものの扱いで便利です。

あらゆる設定が上書き可能ですが、tagregistryaccess が重要です。

上書き可能なオプションは npm-config を参照してください。

参考記事