Zenn
🚀

Nextra4でドキュメントサイトを爆速構築！Zscaler環境でも安心セットアップ

に公開
Next.js
npm
documentation
Nextra
zscaler
tech

.

はじめに

Nextra は、Next.js をベースにした静的サイトジェネレーターで、特にドキュメントサイトの構築を簡単かつ高速に行えるフレームワークです。Markdown でコンテンツを記述でき、コードハイライトや検索機能なども手軽に導入できます。

数年ぶりに社内プロジェクトで導入しようとしたところ、開発職ではない、私の現在の環境(Zsacler下のWindows11)では公式の導入手順(https://nextra.site/docs/docs-theme/start) では、うまくいかず、たくさん躓いたのと、Nextra4になってから日本語の解説サイトが見当たらなかったので、細かいことは気にせずとりあえず、導入できた手順を記録に残します。

この記事では、Nextra を使ってドキュメントサイトの雛形をセットアップし、ローカルで開発環境を起動するまでの一連の手順を、技術にあまり詳しくない方でもわかるように解説します。
特に、企業などの Zscaler を利用しているネットワーク環境下で npm や git コマンドがうまく動作しない場合の対処法についても触れます。

対象読者

  • ドキュメントサイトを手軽に構築したい方
  • Nextra に興味がある方
  • ツールのセットアップに不安がある方
  • Zscaler 環境下で開発ツール（npm, git）の利用に困っている方

事前準備

以下のツールがインストールされていることを確認してください。

Node.js:
JavaScript の実行環境です。npm (Node Package Manager) も一緒にインストールされます。ターミナル（WindowsならコマンドプロンプトやPowerShell、Macならターミナル.app）で node -v と npm -v を実行してバージョンが表示されればOKです。

Git:
バージョン管理システムです。ターミナルで git --version を実行してバージョンが表示されればOKです。

もしインストールされていない場合は、公式サイトからダウンロードしてインストールしてください。

Node.js: https://nodejs.org/
Git: https://git-scm.com/

1. Zscaler 環境下での npm と git の設定 (必要な方のみ)

企業ネットワークなどで Zscaler のようなプロキシやセキュリティソリューションが導入されている場合、SSL/TLS 通信が検査され、npm install や git clone がエラーになることがあります。これは、Zscaler が発行する中間証明書をローカルの npm や git が信頼できないために起こります。この問題を解決するには、Zscaler のルート証明書を取得し、npm と git に信頼させる設定を行います。

参考: Adding a Custom Certificate to an Application Specific Trust Store (Zscaler Help Portal)

Zscaler ルート証明書の取得

まず、お使いの Zscaler 環境のルート証明書（.crt または .pem 形式）を入手します。
多くの場合、IT部門に問い合わせるか、特定のURL (例: https://<お使いのZscalerゲートウェイドメイン>/zscalerrootca.crt など) からダウンロードできます。ファイル名は ZscalerRootCertificate.crt や zscaler.pem のような名前になっていることが多いです。

ここでは例として、証明書ファイルを ~/certs/ZscalerRootCertificate.crt に保存したとします。
ご自身の環境に合わせてパスを読み替えてください。

npm の設定

ターミナルを開き、以下のコマンドを実行します。

npm config set cafile "/path/to/your/ZscalerRootCertificate.crt"

コマンドの説明:

  • npm config set cafile: npm の設定項目 cafile に値を設定します。
  • "/path/to/your/ZscalerRootCertificate.crt": ダウンロードした Zscaler ルート証明書ファイルの絶対パスを指定します。
    • Windows の場合は C:\path\to\your\ZscalerRootCertificate.crt のように指定します。パスにスペースが含まれる場合はダブルクォーテーションで囲ってください。
    • Mac や Linux の場合は /Users/yourusername/certs/ZscalerRootCertificate.crt のようになります。

設定を確認するには、以下のコマンドを実行します。

npm config get cafile

指定したパスが表示されればOKです。

Gitの設定

同様に、Git に対してもルート証明書を設定します。ターミナルで以下のコマンドを実行します。

git config --global http.sslCAInfo "/path/to/your/ZscalerRootCertificate.crt"

コマンドの説明:

  • git config --global http.sslCAInfo: Git の全リポジトリ共通の設定として http.sslCAInfo に値を設定します。
  • "/path/to/your/ZscalerRootCertificate.crt": npm と同様に、Zscaler ルート証明書ファイルの絶対パスを指定します。

設定を確認するには、以下のコマンドを実行します。

git config --global --get http.sslCAInfo

指定したパスが表示されればOKです。

これで、Zscaler 環境下でも npm や git が HTTPS 通信を正しく行えるようになるはずです。

どうしてもルート証明書が入手できない場合、一時的な回避策として SSL/TLS の検証を無効にすることができます。

npm で SSL/TLS 検証を一時的に無効にする

npm install などのコマンド実行時に、環境変数 NODE_TLS_REJECT_UNAUTHORIZED を 0 に設定することで、そのコマンド実行中のみ SSL/TLS 検証が無効になります。

コマンド実行例 (npm install の場合):

NODE_TLS_REJECT_UNAUTHORIZED=0 npm install

または (Windows のコマンドプロンプトの場合):

set NODE_TLS_REJECT_UNAUTHORIZED=0 && npm install

(Windows PowerShell の場合):

$env:NODE_TLS_REJECT_UNAUTHORIZED=0; npm install

この方法は、コマンドを実行するたびに環境変数を指定する必要があるため手間がかかりますが、影響範囲をそのコマンド実行のみに限定できます。

恒久的に無効にする設定 (npm config set strict-ssl false) もありますが、セキュリティリスクが高いため推奨しません。

Git で SSL/TLS 検証を無効にする

Git で SSL/TLS 検証を無効にするには、以下のコマンドを実行します。

git config --global http.sslVerify false

コマンドの説明:

  • git config --global http.sslVerify false: Git の全リポジトリ共通の設定として、SSL 証明書の検証を行わないようにします。

設定の確認:

git config --global --get http.sslVerify

false と表示されれば設定されています。

重要: この設定はセキュリティリスクを伴うため、必要な操作が完了したら、以下のコマンドで設定を元に戻すことを強く推奨します。

# 設定を削除 (デフォルトの true に戻る)
git config --global --unset http.sslVerify
# もしくは明示的に true に設定
# git config --global http.sslVerify true

🚨 SSL/TLS の検証を無効化はセキュリティ上のリスクを伴います。可能な限り、ルート証明書を利用した正規の方法で設定してください。

2. Nextra デモサイトのセットアップ

今回は、基本的な Nextra の機能が含まれたデモサイト (officialrajdeepsingh/nextra-4) を元にセットアップを進めます。

2.1. デモサイトのソースコードをクローンする

まず、ターミナルを開き、作業したいディレクトリに移動します。
次に、git clone コマンドを使って、デモサイトのソースコードをローカルマシンにコピーします。

git clone https://github.com/officialrajdeepsingh/nextra-4

コマンドを実行すると、カレントディレクトリに nextra-4 という名前のフォルダが作成され、その中にソースコードがダウンロードされます。

2.2. プロジェクトディレクトリに移動する

ソースコードの準備ができたら、プロジェクトのフォルダに移動します。

cd nextra-4

2.3. 必要なライブラリをインストールする

Nextra プロジェクトを実行するためには、いくつかのライブラリ（依存パッケージ）が必要です。これらは package.json ファイルにリストされており、npm install コマンドで一括インストールできます。

nextra-4 フォルダ内で、以下のコマンドを実行してください。

npm install

インターネットの速度やPCのスペックにもよりますが、数秒から数分程度でインストールが完了します。node_modules というフォルダが作成され、その中に必要なライブラリがダウンロードされます。

2.4. 開発環境を起動する

ライブラリのインストールが完了したら、いよいよ開発サーバーを起動します。
以下のコマンドを実行してください。

npm run dev

このコマンドは、package.json ファイル内の scriptsセクションに定義されている dev という名前のスクリプトを実行します。通常、Next.js (Nextra) のプロジェクトでは、開発モードでサーバーを起動するコマンドが設定されています。

コマンドが成功すると、ターミナルに以下のようなメッセージが表示されます (ポート番号などは環境によって変わることがあります)。

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
event - compiled client and server successfully in 1835 ms (20 modules)

http://localhost:3000 というURLが表示されているのがわかります。

2.5. ブラウザで確認する

ウェブブラウザ（Google Chrome, Firefox, Edge など）を開き、アドレスバーに http://localhost:3000 と入力してアクセスしてください。

デモサイトが表示されれば、セットアップは成功です！🎉

開発サーバーを停止するには、ターミナルで Ctrl + C (コントロールキーを押しながら C キー) を押してください。

まとめ

この記事では、Nextra のデモサイトをローカル環境にセットアップし、開発サーバーを起動するまでの手順を解説しました。また、Zscaler 環境下で npm や git を利用するための設定方法についても触れました。

Nextra を使えば、Markdown で手軽に高機能なドキュメントサイトを構築できます。
ここから、pages フォルダ内の .md や .mdx ファイルを編集して、ご自身のコンテンツを作成してみてください。

Happy Documenting! 📄✍️

Discussion