開発環境を準備する

この章でわかること

この章では、Square APIとNext.jsを使ってECシステムを作るための開発環境を準備します。

ここから、いよいよ手を動かしていきます。

ただし、最初から難しいコードを書く必要はありません。

まずは、次のものを揃えます。

Next.jsプロジェクト
TypeScript
Tailwind CSS
Square Sandbox
環境変数
GitHub
Vercel

攻略本でいうと、この章は「冒険に出る前の装備チェック」です。

武器を持たずにボス戦へ行かないように、EC開発でも最初に環境を整えておきます。

---

4.1 使用技術スタック

本書では、次の技術スタックを使います。

Next.js
TypeScript
Tailwind CSS
Square API
Square Sandbox
GitHub
Vercel

それぞれの役割は次の通りです。

技術	役割
Next.js	ECサイト本体を作る
TypeScript	コードのミスを減らす
Tailwind CSS	画面デザインを効率よく作る
Square API	決済リンクや決済処理を扱う
Square Sandbox	テスト用のSquare環境
GitHub	ソースコードを管理する
Vercel	Next.jsを公開する

本書では、Next.jsのApp Routerを使います。

Next.js公式ドキュメントでは、App RouterはReact Server Componentsなどの新しいReact機能をサポートするルーターとして説明されています。新規プロジェクトでは、create-next-appを使うことでTypeScriptやESLintなどを含む構成を自動作成できます。(nextjs.org, nextjs.org)

本書の基本方針

本書では、次のような設計で進めます。

画面
↓
Next.js

型安全
↓
TypeScript

デザイン
↓
Tailwind CSS

決済
↓
Square API

公開
↓
Vercel

まずは、この役割分担だけ覚えれば大丈夫です。

---

4.2 Next.jsプロジェクトの作成

まず、Next.jsプロジェクトを作成します。

公式ドキュメントでは、create-next-appがNext.jsアプリを始める最も簡単な方法として案内されています。(nextjs.org)

ターミナルで次のコマンドを実行します。

pnpm create next-app square-next-ec

pnpmを使わない場合は、npmでも構いません。

npx create-next-app@latest square-next-ec

作成時に質問が表示されたら、次のように選びます。

TypeScript
↓
Yes

ESLint
↓
Yes

Tailwind CSS
↓
Yes

src directory
↓
Yes

App Router
↓
Yes

Turbopack
↓
任意

Import alias
↓
Yes

プロジェクト作成後、フォルダに移動します。

cd square-next-ec

開発サーバーを起動します。

pnpm dev

ブラウザで次のURLを開きます。

http://localhost:3000

Next.jsの初期画面が表示されれば成功です。

攻略ポイント

最初のゴールは、

localhostでNext.jsが表示されることです。

ここでエラーが出る場合、Square APIの設定に進む前に直します。

Next.jsが起動しない
↓
Square連携には進まない

Next.jsが表示される
↓
次のステージへ進む

---

4.3 TypeScript設定

TypeScriptは、JavaScriptに型を追加した言語です。

ECでは、商品、注文、決済、在庫など、扱うデータが多くなります。

型がないと、次のようなミスが起きやすくなります。

価格が文字列なのか数値なのかわからない
商品IDを間違える
注文ステータスの値を間違える
存在しないプロパティを使う
APIレスポンスの形を勘違いする

TypeScriptを使うと、こうしたミスを事前に見つけやすくなります。

Next.jsはTypeScriptを標準的にサポートしており、create-next-appでTypeScriptを選択すると必要な設定が作られます。(nextjs.org)

最初に作る型

ECでは、まず次のような型を用意します。

export type Product = {
  id: string;
  slug: string;
  name: string;
  description: string;
  price: number;
  currency: 'JPY';
  imageUrl: string;
  isAvailable: boolean;
};

この型があると、商品データの形がはっきりします。

id
↓
商品を識別するID

slug
↓
URLに使う文字列

name
↓
商品名

price
↓
価格

currency
↓
通貨

imageUrl
↓
商品画像

isAvailable
↓
販売中かどうか

攻略ポイント

TypeScriptは、最初は少し面倒に感じます。

しかし、ECでは必須装備です。

攻略本でいうと、

ミスを事前に知らせてくれる防具です。

特に、価格や注文ステータスは型で守ります。

---

4.4 Tailwind CSSの導入

Tailwind CSSは、HTMLやReactコンポーネントにクラス名を書いてデザインを作るCSSフレームワークです。

Tailwind CSS公式では、ユーティリティファーストのCSSフレームワークとして説明されています。あらかじめ用意された小さなクラスを組み合わせて、画面を作っていきます。(tailwindcss.com)

Next.js作成時にTailwind CSSを選択していれば、基本設定はすでに入っています。

もし手動で入れる場合は、Tailwind CSS v4系では、PostCSSプラグインを追加し、グローバルCSSで@import "tailwindcss";を読み込む流れが公式ドキュメントで案内されています。(tailwindcss.com, nextjs.org)

インストール例です。

pnpm add -D tailwindcss @tailwindcss/postcss

postcss.config.mjsを確認します。

const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

export default config;

src/app/globals.cssにTailwindを読み込みます。

@import "tailwindcss";

Tailwind CSSで何が楽になるか

ECサイトでは、同じようなUIを何度も作ります。

商品カード
購入ボタン
価格表示
カテゴリラベル
在庫表示
注意書き
フォーム
管理画面のテーブル

Tailwind CSSを使うと、これらを素早く作れます。

たとえば、購入ボタンは次のように書けます。

export function BuyButton() {
  return (
    <button className="rounded-md bg-black px-6 py-3 text-sm font-semibold text-white">
      購入する
    </button>
  );
}

攻略ポイント

Tailwind CSSは、デザインを素早く組むための道具です。

ただし、クラス名が長くなりすぎる場合は、コンポーネントに分けます。

同じ見た目を何度も使う
↓
コンポーネント化する

一度しか使わない見た目
↓
その場でTailwindを書く

---

4.5 環境変数の設計

環境変数とは、コードに直接書きたくない設定値を外に出して管理する仕組みです。

Next.js公式ドキュメントでは、.env*ファイルから環境変数を読み込み、process.env経由で利用できると説明されています。(nextjs.org)

EC開発では、環境変数がとても重要です。

特にSquare APIを使う場合、Access Tokenのような秘密情報を扱います。

.env.localを作成します。

touch .env.local

最初は次のように用意します。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=ここにSandboxのAccess Tokenを入れる
SQUARE_LOCATION_ID=ここにSandboxのLocation IDを入れる
SQUARE_WEBHOOK_SIGNATURE_KEY=ここにWebhook署名キーを入れる
NEXT_PUBLIC_APP_URL=http://localhost:3000

**NEXT_PUBLIC_**の注意点

Next.jsでは、NEXT_PUBLIC_が付いた環境変数はブラウザ側にも公開されます。

そのため、秘密情報には絶対にNEXT_PUBLIC_を付けません。

公開してよい
↓
NEXT_PUBLIC_APP_URL

公開してはいけない
↓
SQUARE_ACCESS_TOKEN
SQUARE_WEBHOOK_SIGNATURE_KEY
DB_PASSWORD

悪い例です。

NEXT_PUBLIC_SQUARE_ACCESS_TOKEN=これは絶対にダメ

よい例です。

SQUARE_ACCESS_TOKEN=サーバー側だけで使う

攻略ポイント

環境変数は、鍵付きの宝箱です。

宝箱の中身をブラウザに見せてはいけません。

秘密情報
↓
サーバー側だけ

公開情報
↓
NEXT_PUBLIC_を付けてもよい

---

4.6 Square Sandbox環境の準備

Square Sandboxは、テスト用のSquare環境です。

本物のお金を動かさずに、APIや決済の動作を確認できます。

Square公式ドキュメントでは、Squareの開発者アカウントを作成するとDefault Test Accountが作られ、Sandbox APIリクエストで使えるAccess Tokenが生成されると説明されています。(developer.squareup.com)

Sandboxでできること

テスト用の決済を試す
テスト用の商品を作る
テスト用の注文を確認する
APIの動作確認をする
Webhookのテストをする

Sandboxでやってはいけないこと

本番の売上として扱う
本番の顧客情報を入れる
本番用Access Tokenと混ぜる

Sandboxは、練習場です。

本番の店舗とは分けて考えます。

Sandbox
↓
テスト用の世界

Production
↓
本番の世界

攻略ポイント

Square連携は、必ずSandboxから始めます。

いきなり本番Access Tokenを使って開発しないことが重要です。

---

4.7 Access TokenとLocation IDの取得

Square APIを使うには、Access TokenとLocation IDが必要です。

Square公式では、Access TokenはSquare APIへアクセスするための認証情報であり、顧客、注文、決済などSquareアカウント内のリソースへのアクセスを許可するものと説明されています。(developer.squareup.com)

Access Tokenの取得

Square Developer Consoleにログインします。

次の流れで確認します。

Square Developer Consoleを開く
↓
Applicationsを開く
↓
対象アプリを選ぶ
↓
Credentialsを開く
↓
Sandbox Access Tokenを確認する

取得したAccess Tokenを.env.localに設定します。

SQUARE_ACCESS_TOKEN=SandboxのAccess Token

Location IDの取得

Location IDは、Square上の店舗や事業所を表すIDです。

Square Developer ConsoleのSandbox test accountsでは、テストアカウントを開いてAccess Tokenを確認したり、Sandbox Square Dashboardを開いてアカウントデータを確認できます。(developer.squareup.com)

Location IDは、Developer ConsoleやSquare Dashboard、またはLocations APIから取得できます。

.env.localに設定します。

SQUARE_LOCATION_ID=SandboxのLocation ID

攻略ポイント

Access TokenとLocation IDはセットで覚えます。

Access Token
↓
Square APIを使うための鍵

Location ID
↓
どの店舗・事業所の処理かを示すID

この2つがないと、Square API連携は始まりません。

---

4.8 本番環境とSandbox環境の分離

EC開発では、本番環境とテスト環境を絶対に混ぜないことが重要です。

Squareでは、SandboxとProductionを分けて使います。

Sandbox
↓
テスト用

Production
↓
本番用

Next.js側でも、環境変数を分けます。

開発環境

.env.localではSandboxを使います。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=Sandbox用Access Token
SQUARE_LOCATION_ID=Sandbox用Location ID
NEXT_PUBLIC_APP_URL=http://localhost:3000

本番環境

VercelのProduction環境では、本番用の値を使います。

SQUARE_ENVIRONMENT=production
SQUARE_ACCESS_TOKEN=本番用Access Token
SQUARE_LOCATION_ID=本番用Location ID
NEXT_PUBLIC_APP_URL=https://example.com

Preview環境

VercelのPreview環境では、Sandboxを使うのがおすすめです。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=Sandbox用Access Token
SQUARE_LOCATION_ID=Sandbox用Location ID
NEXT_PUBLIC_APP_URL=https://preview-url.vercel.app

Vercel公式ドキュメントでは、環境変数はProject Settingsで設定でき、Production、Preview、Developmentなどの環境ごとに値を分けられると説明されています。(vercel.com)

攻略ポイント

本番とSandboxを混ぜると、事故が起きます。

開発中に本番決済が動く
↓
危険

本番サイトでSandbox決済が動く
↓
売上にならない

環境変数で明確に分けます。

---

4.9 GitHubとVercelの接続

Next.jsアプリを公開するために、GitHubとVercelを接続します。

基本の流れは次の通りです。

ローカルで開発
↓
GitHubへpush
↓
Vercelが自動デプロイ
↓
URLが発行される

GitHubリポジトリを作る

まず、Gitを初期化します。

git init
git add .
git commit -m "Initial commit"

GitHubで新しいリポジトリを作り、リモートを登録します。

git remote add origin https://github.com/ユーザー名/square-next-ec.git
git branch -M main
git push -u origin main

Vercelに接続する

Vercelにログインし、GitHubリポジトリをImportします。

Vercel公式ドキュメントでは、Next.jsプロジェクトをVercelにデプロイすると、Preview DeploymentやProduction Deploymentなどの環境を利用できると説明されています。(vercel.com)

流れは次の通りです。

Vercelにログイン
↓
Add New Project
↓
GitHubリポジトリを選択
↓
Framework PresetがNext.jsになっていることを確認
↓
Environment Variablesを設定
↓
Deploy

環境変数をVercelに設定する

Vercel側にも環境変数を設定します。

SQUARE_ENVIRONMENT
SQUARE_ACCESS_TOKEN
SQUARE_LOCATION_ID
SQUARE_WEBHOOK_SIGNATURE_KEY
NEXT_PUBLIC_APP_URL

ローカルの.env.localはGitHubにpushしません。

Vercelには、Vercelの管理画面から環境変数を設定します。

攻略ポイント

GitHubはコード置き場です。

Vercelは公開場所です。

GitHub
↓
コードを管理する

Vercel
↓
サイトを公開する

秘密情報はGitHubに置かず、VercelのEnvironment Variablesに設定します。

---

4.10 開発時にやってはいけない秘密情報の扱い

EC開発では、秘密情報の扱いを間違えると重大な事故になります。

特に注意すべきものは、次の通りです。

Square Access Token
Webhook Signature Key
DB接続情報
メールAPIキー
管理者パスワード
本番環境のURL設定

やってはいけないこと

Access TokenをGitHubにpushする
Client Componentに秘密情報を書く
NEXT_PUBLIC_を付けて秘密情報を公開する
スクリーンショットでTokenを共有する
SlackやLINEにTokenをそのまま貼る
本番Tokenをテストで使う
.env.localをリポジトリに含める

**.gitignore**を確認する

.env.localが.gitignoreに含まれているか確認します。

.env*

ただし、.env.exampleは作っておくと便利です。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=
SQUARE_LOCATION_ID=
SQUARE_WEBHOOK_SIGNATURE_KEY=
NEXT_PUBLIC_APP_URL=http://localhost:3000

.env.exampleには、実際の秘密情報を書きません。

他の開発者が何を設定すればよいかだけを示します。

秘密情報を漏らした場合

もしAccess Tokenを漏らした場合は、放置してはいけません。

すぐに次の対応を行います。

漏洩したTokenを無効化する
新しいTokenを発行する
Vercelの環境変数を更新する
Git履歴に残っていないか確認する
必要に応じてリポジトリの履歴を修正する

Square公式でも、Access TokenはSquare APIへアクセスできる重要な認証情報であり、適切な管理と保管が重要だと説明されています。(developer.squareup.com)

攻略ポイント

秘密情報は、ゲームでいう「マスターキー」です。

マスターキーを渡すと、誰でも城に入れてしまいます。

秘密情報
↓
コードに書かない
GitHubに上げない
ブラウザに出さない
人に送らない

このルールは、EC開発では必ず守ります。

---

この章のまとめ

この章では、Square APIとNext.jsでECを作るための開発環境を準備しました。

今回そろえた装備は、次の通りです。

Next.js
TypeScript
Tailwind CSS
Square Sandbox
環境変数
GitHub
Vercel

まず、Next.jsプロジェクトを作成しました。

次に、TypeScriptで安全にデータを扱う準備をしました。

Tailwind CSSで画面を作る準備も整えました。

Square Sandboxを使うことで、本物のお金を動かさずにAPIや決済のテストができます。

そして、GitHubとVercelを使って、コード管理と公開の準備をしました。

特に重要なのは、環境変数と秘密情報の扱いです。

Access Token
↓
サーバー側だけで使う

NEXT_PUBLIC_
↓
公開してよい値だけに付ける

Sandbox
↓
テスト用

Production
↓
本番用

このルールを守ることで、安全にEC開発を進められます。

---

次の章でやること

次の章では、商品一覧ページを作ります。

まずは、静的な商品データを用意し、商品カードを表示します。

商品名、価格、説明、画像、販売状態をTypeScriptで型定義し、Next.jsの画面に表示していきます。

ここから、ユーザーが実際に見るECサイトの形が少しずつ見えてきます。