補足

本記事で使用している Gatsby はバージョン 4 です。他のバージョンでは当てはまらない内容があるかもしれません。


このブログのジェネレーターについて Hugo から Gatsby への移行を試みました。Gatsby のプロジェクトを作成するまでに複数の方法が考えられ、調べてみるとところにより三者三様な手順となっていたため、備忘録代わりに整理・記録しておきます。

グローバルにインストールするかプロジェクトにインストールするか

これは Gatsby だけに限った話ではないですが、どこにパッケージをインストールするかですね。

グローバルにインストールする場合

npm でグローバルに入れるならば以下です。

npm install -g gatsby-cli

または Homebrew で入れたいなら以下です。

https://formulae.brew.sh/formula/gatsby-cli

brew install gatsby-cli

プロジェクトを作成する

そしてグローバルにインストールしたあと、以下を実行すればプロジェクトが作成されます。

gatsby new

プロジェクトごとにインストールする場合

以下で Gatsby のインストールおよびプロジェクト作成が完了します。

npm init gatsby

npm init の後にパッケージ名を指定する書き方を見かけたことがなかったため、何が起きているのかちょっと調べてみました。

npm-init

npm init <initializer> can be used to set up a new or existing npm package.

initializer in this case is an npm package named create-<initializer>, which will be installed by npm-exec, and then have its main bin executed – presumably creating or updating package.json and running any other initialization-related operations.

The init command is transformed to a corresponding npm exec operation as follows:

  • npm init foo -> npm exec create-foo
  • npm init @usr/foo -> npm exec @usr/create-foo
  • npm init @usr -> npm exec @usr/create

If the initializer is omitted (by just calling npm init), init will fall back to legacy init behavior. It will ask you a bunch of questions, and then write a package.json for you.

https://docs.npmjs.com/cli/v8/commands/npm-init

つまり npm init gatsby は以下を実行しているのと同じということです。

npm exec create-gatsby

または以下も同じです。

npx create-gatsby

そして、このとき実行されている create-gatsby というパッケージはこれですね。

https://www.npmjs.com/package/create-gatsby

また、厳密にいうと npm execnpx では引数の指定方法が違うようですが、上記の例だとどちらも全く変わりません。

npx vs npm exec

When run via the npx binary, all flags and options must be set prior to any positional arguments. When run via npm exec, a double-hyphen -- flag can be used to suppress npm’s parsing of switches and options that should be sent to the executed command.

https://docs.npmjs.com/cli/v8/commands/npm-exec

あとさらに追加で、これも同様にグローバルにはインストールせずプロジェクトを作成する動きになりますね。

npx gatsby new

そして最後に、以下のように手動でプロジェクトを作成することももちろん可能です。

これまで実行してきたコマンドが行っていることは主に以下3つのパッケージのインストールと、設定ファイルやディレクトリの生成に過ぎません。

npm install react react-dom gatsby

上記をインストール後、package.json に以下を追加して npm run develop すると、他と同様にサーバを立ち上げることができます。

{
  "scripts": {
    "develop": "gatsby develop"
  }
}

インストール方法整理

脇道に外れたりしつつ書き連ねてきてしまったので、改めてここにパターンを整理しておきます。

グローバルにインストール / プロジェクト生成

  • npm install -g gatsby-cli して gatsby new
  • brew install gatsby-cli して gatsby new

プロジェクトごとにインストール / プロジェクト生成

  • npm init gatsby
  • npm exec create-gatsby
  • npx create-gatsby
  • npx gatsby new
  • npm install react react-dom gatsby して、その他ファイルを手動で作成

それぞれのコマンドで生成されるプロジェクトの中身が違う

以上で見た通りインストール方法がいくつか考えられるわけですが、それぞれのコマンドで生成されるプロジェクトの中身が異なるのが注意が必要なところです。

gatsby-cli で gatsby new の場合

  • npm install -g gatsby-cli して gatsby new
  • brew install gatsby-cli して gatsby new

これは上記のパターンで作成した場合についてです。

gatsby-cli で gatsby new とした場合、「gatsby-starter-default」というスターターを用いてプロジェクトが作成されます。

Execute the gatsby new command to clone a boilerplate starter, install its dependencies, and clear Git history.

https://www.gatsbyjs.com/docs/starters/

gatsby-starter-default はこれですね。

https://github.com/gatsbyjs/gatsby-starter-default

上記のリポジトリにある内容がそのままクローンされる形でプロジェクトが生成されます。

設定ファイルを見ると初期状態で色々書かれていたり、package.json を見ると最初から色々なプラグインが入っている状態となっています。

これでサーバを立ち上げて http://localhost:8000/ にアクセスすると、Gatsby Default Starter のトップページである、

Hi people

Welcome to your new Gatsby site.

Now go build something great.

こちらのページが開きます。

npm init gatsby 系の場合

  • npm init gatsby
  • npm exec create-gatsby
  • npx create-gatsby
  • npx gatsby new

これは上記のパターンで作成した場合についてです。

こちらの場合、スターターは用いられずにプロジェクトが作成されます。

以下が作成されるディレクトリ・ファイルです。シンプルなことがわかります。

├ .git/
├ .gitignore
├ README.md
├ gatsby-config.js
├ node_modules/
├ package-lock.json
├ package.json
└ src/
  ├ images/
  └ pages/

作成された package.json は以下です。

package.json

{
  "name": "gatsby-example-project",
  "version": "1.0.0",
  "private": true,
  "description": "gatsby-example-project",
  "author": "Jane Doe",
  "keywords": ["gatsby"],
  "scripts": {
    "develop": "gatsby develop",
    "start": "gatsby develop",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "clean": "gatsby clean"
  },
  "dependencies": {
    "gatsby": "^4.4.0",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  }
}

そして http://localhost:8000/ にアクセスすると、

Congratulations — you just made a Gatsby site! 🎉🎉🎉

から始まる、公式ドキュメントへのリンク集のページが表示されます。

npm install react react-dom gatsby の場合

  • npm install react react-dom gatsby して、その他ファイルを手動で作成

上記のパターンで作成した場合についてです。

当然ながら上記を実行しただけでは以下の3ファイルのみしか生成されません。その他のファイルは自分で作成します。

├ node_modules/
├ package-lock.json
└ package.json

おわり

ということで以上です。私はグローバルにインストールしたくない派閥なので、とりあえず npm init gatsby で作ると思います。

ちなみに移行作業は問題なく行えていたものの、最終的に移行の実施はやめてしまいました。もともと強い必要性があったわけでもなく、試しに Gatsby 使ってみるかといった程度でしたが、いざ使い始めてみて、ビルドが爆速な Hugo の方が好きだなと感じました。

一方で拡張性については Gatsby の方が優っていると感じたので、将来的にこのブログに色々手を加えたくなった際は改めて移行するかもしれません。