「動く」と「使える」の差は4つの状態 — Reactの画面

Reactの画面づくり。状態の異なる四つの小さなアプリ画面とフォームの部品。

「動く」と「使える」の差は4つの状態です。読み込み中・成功・空・エラーを、Reactの画面で全部作ります。

前回: 全部書いてから動かさない — 作品のAPIと認証 作業場所はVMの中(Ubuntu Server)、確認はホストの Windows のブラウザです。前回作った ~/hitokoto/(Express + MySQL)がそのまま動いている前提です。

前回で、hitokoto のサーバー側は完成しました。curl を叩けば JSON が返ってきます。エラーの形も { error: { code, message } } に揃えました。

ここで、多くの人が油断します。 「あとは画面を貼るだけだ」と思うからです。

そうはなりません。 理由は、作るものの性質が変わるからです。

サーバー側(前回)画面側(今回)
相手プログラム人間
正解の判定返り値が仕様どおりか。機械が判定できる触った人が分かるか。機械には判定できない
「できた」の基準テストが通ったら完成テストが通っても、使えないことがある

いちばん大きいのは、最後の行です。

API は「正しく動く」で合格ですが、画面は「正しく動く」だけでは不合格です。

たとえば、あなたの画面が API から本の一覧を取ってきて表示するとします。コードは正しく動いています。 けれど、通信に0.8秒かかる間、画面は真っ白です。触った人は「壊れている」と思って、リロードします。

コードにバグはありません。それでも、使えません。

この記事は、その差を埋める作業です。新しい技術は1つも出てきません。 React、ルーティング、fetch と非同期、CSS変数、nginx。全部やったものです。

やることは、それを1つのアプリとして組み上げて、「動く」から「使える」まで持っていくことだけです。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • 画面が「動いている」ことと「使える」ことは別だということ。バグがゼロでも使えない画面が普通に作れる
  • 1つの表示には状態が4つあること(読み込み中 / 空っぽ / エラー / 正常)。正常だけ書いて出すと、残り3つは「真っ白」という同じ見た目に潰れる
  • 一番忘れられるのは「空っぽ」だということ。自分のデータで開発しているので、開発者は空の画面をほとんど見ない。なのに、初めて使う人が最初に見るのはその画面
  • 開発中のCORSは、サーバーを直して解決するものではないこと。Vite のプロキシで「同じ場所から来ているように見せる」ほうが、本番の形に近い
  • デザインは「決め直さない」こと。前回作ったトークンと Button をそのまま持ってくる。新しい色を1つも足さない

この記事でやること

  1. ~/hitokoto/web を Vite で作り、server.proxy で /api をバックエンドに転送してCORSを消す
  2. 画面を3枚だけ作る(一覧 / 登録 / 公開ページ)。ルーティングで繋ぐ
  3. 一覧画面に、4つの状態(読み込み中・空・エラー・正常)を全部書く
  4. 登録フォームを「壊れない」形にする(送信中はボタンを止める / 失敗しても入力を消さない / どこが悪いか出す)
  5. npm run build して、nginx から dist/ を配り、/api をプロキシして本番の形で確認する

先に知る言葉

この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめています。

言葉ここでの意味
状態(UIの状態)画面が取りうる見た目のパターン。「読み込み中」「空」「エラー」「正常」の4つを指す
空状態(からじょうたい)データが0件のときに出す画面。「0件です」ではなく「これから何をすればいいか」を出す場所
プロキシ(開発サーバーの)開発サーバーが、特定のパスへの要求を別のサーバーへ黙って転送すること。ブラウザからは1つのサーバーに見える
CORS別のオリジン(プロトコル + ホスト + ポートの組)へのブラウザからの通信を、既定で止める仕組み。ブラウザだけの制限で、curl では起きない
二重送信送信ボタンを2回押されて、同じデータが2件登録されてしまうこと
楽観的更新サーバーの返事を待たずに、先に画面を更新してしまうやり方。この記事ではやりません

① 作るものを、もう一度1枚に書く

コードを書く前に、何を作るのかを紙1枚に落とします。 これをやらないと、途中で画面が増えます。

hitokoto は、読んだ本と、そこから引いた一文を残すアプリです。画面は3枚だけです。

画面URL何をする
一覧/自分が登録した一文を、新しい順に並べる
登録/new本を選び(または新しく足し)、一文を書いて保存する
公開/publicログインしていない人でも読める、公開された一文の一覧

使う API は、前回作ったこれだけです。

メソッドパス用途
POST/api/loginログイン
GET/api/books自分の本の一覧
POST/api/books本を足す
GET/api/quotes自分の一文の一覧
POST/api/quotes一文を足す
GET/api/public/quotes公開されている一文の一覧(ログイン不要)

エラーは全部この形で返ってきます。

{ "error": { "code": "VALIDATION_ERROR", "message": "本文は必須です" } }

この表を先に書いておくと、後で「あ、この画面も要る」が減ります。 画面を1枚足すたびに、状態が4つ増え、リンクが増え、スマホでの確認が増えます。 3枚は少ないのではなく、意図的に少なくしています。

② ~/hitokoto/web を Vite で作る

サーバーと同じフォルダの中に作ります。 VMの中で打ちます。

bash
$ cd ~/hitokoto
$ npm create vite@latest web -- --template react

-- の後ろが npm create ではなく、その先の道具に渡る引数です。npmの回でやった npm run dev -- --host と同じ書き方です。

続けて依存を入れます。

bash
$ cd ~/hitokoto/web
$ npm install
$ npm install react-router-dom

確認します。

bash
$ ls ~/hitokoto
node_modules  package.json  src  web  knexfile.js  migrations

web/ が増えていれば成功です。

[スクリーンショット: 01_web作成直後.png] ls ~/hitokoto の結果を撮ってください。web が並んでいるところが見える形で。

なぜ、サーバーと同じリポジトリに置くのか

別々にすることもできます。 実際、仕事では分けることも多いです。ここでは、あえて同じ場所に置きます。理由は3つです。

1つめ。API を変えたら、画面も一緒に変わるから。

POST /api/quotes の必須項目を1つ増やしたとします。画面側も同じ瞬間に直さないと壊れます。 別リポジトリだと、「どのコミットとどのコミットが対になっているか」を人間が覚えることになります。

2つめ。1人で作っているから。

リポジトリを分ける最大の理由は、別のチームが別の速度で動くからです。それが無いなら、分ける理由もありません。

3つめ。後から分けるのは簡単で、後から統合するのは面倒だから。

迷ったら、まとめておくほうが戻せます。

ただし、混ぜてはいけないものが1つあります。 web/ の package.json と、サーバー側の package.json は別のファイルのままにします。 依存が混ざると、「ブラウザに送るコードの中に、データベース接続のライブラリが紛れ込む」ことが起こり得ます。 フォルダは同じ、依存は別です。

動くことだけ先に確認する

bash
$ cd ~/hitokoto/web
$ npm run dev -- --host

--host は、VMの外(Windows側のブラウザ)から見えるようにするためのものです(Reactの回から使っています)。

Windows のブラウザで http://192.168.226.50:5173/ を開き、Vite の初期画面が出れば成功です。IPは自分のVMのものに読み替えてください(ip a で確認できます。ネットワークの回)。

戻し方: ここまでで失敗したら、rm -rf ~/hitokoto/web で丸ごと消してやり直せます。サーバー側には一切触っていません。

③ 開発中のCORSを、プロキシで消す

ここで、初めての人が必ず1回踏む地雷があります。

いまの状態は、こうなっています。

動いているものポート
Vite の開発サーバー(画面)5173
Express(API)3001

画面から fetch('http://192.168.226.50:3001/api/quotes') を呼ぶと、開発者ツールの Console にこう出ます。

Access to fetch at 'http://192.168.226.50:3001/api/quotes' from origin
'http://192.168.226.50:5173' has been blocked by CORS policy

ホストは同じなのに、ポートが違うので「別のオリジン」です。ブラウザが止めています。

ここで、多くの人はサーバー側に cors パッケージを入れて全部許可します。 動きます。が、それは最善ではありません。

本番では、画面も API も同じオリジンから配られる予定です。 本番で起きない問題を、サーバー側の設定を緩めて回避すると、「開発でしか使わない緩い設定」が本番にも残ります。

やるべきは、開発中も「同じオリジンに見せる」ことです。 Vite にその機能があります。

~/hitokoto/web/vite.config.js を丸ごと置き換えます。

bash
$ nano ~/hitokoto/web/vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: true,
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:3001',
        changeOrigin: true,
      },
    },
  },
})

これで、何が変わるか。

書き方ブラウザから見た宛先実際に処理する人
前: fetch('http://192.168.226.50:3001/api/quotes')ポート3001(別オリジン)Express
後: fetch('/api/quotes')ポート5173(同じオリジン)Vite が3001へ転送して Express

ブラウザから見れば、通信相手は1つだけです。だから CORS は起きません。これはnginxのリバースプロキシでやったことと、まったく同じ考え方です。開発用に小さいものが Vite に付いている、というだけです。

host: true は、さっきの --host を設定ファイルに書いたものです。これで毎回打たなくてよくなります。

確認します。 Express を別のターミナルで起動したうえで、Vite を再起動します。

bash
$ cd ~/hitokoto/web
$ npm run dev

ブラウザで http://192.168.226.50:5173/api/public/quotes を直接開いてください。JSON が返ってくれば、プロキシが効いています。

[スクリーンショット: 02_プロキシ確認.png] http://<VMのIP>:5173/api/public/quotes をブラウザで開き、JSON が表示されている画面を撮ってください。

効いていないときの見分け方: ここで Vite の「index.html」が返ってきたら、vite.config.js が読み込まれていません。Vite を再起動していないだけのことが多いです。設定ファイルの変更は、ホットリロードでは反映されません。

④ 画面を3枚だけ作る

まず、API を呼ぶところを1ファイルにまとめます。画面の中に fetch を散らかさないためです。

bash
$ mkdir -p ~/hitokoto/web/src/api ~/hitokoto/web/src/pages ~/hitokoto/web/src/components
$ nano ~/hitokoto/web/src/api/client.js
async function request(path, options = {}) {
  const res = await fetch(path, {
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    ...options,
  })

  let body = null
  try {
    body = await res.json()
  } catch {
    body = null
  }

  if (!res.ok) {
    const message = body?.error?.message ?? `通信に失敗しました(${res.status})`
    const err = new Error(message)
    err.code = body?.error?.code ?? 'UNKNOWN'
    err.status = res.status
    throw err
  }

  return body
}

export const api = {
  listQuotes: () => request('/api/quotes'),
  listPublicQuotes: () => request('/api/public/quotes'),
  listBooks: () => request('/api/books'),
  createBook: (data) => request('/api/books', { method: 'POST', body: JSON.stringify(data) }),
  createQuote: (data) => request('/api/quotes', { method: 'POST', body: JSON.stringify(data) }),
  login: (data) => request('/api/login', { method: 'POST', body: JSON.stringify(data) }),
}

この40行が、この記事でいちばん効いてきます。理由は3つです。

1つめ。fetch は、404 や 500 でも例外を投げません。

非同期の回でやったとおりです。「サーバーに届いて、返事が返ってきた」時点で fetch は成功です。中身が「見つかりません」でも成功です。

if (!res.ok) { ... throw ... }

この3行を書かないと、エラー画面が一生出ません。 代わりに undefined が画面に流れ込んで、「Cannot read properties of undefined」で落ちます。DOMの回で見たのと同じ形の事故です。

2つめ。エラーの形を、ここで1回だけ翻訳します。

サーバーは { error: { code, message } } で返してきます。画面のあちこちで body.error.message と書くと、形を変えたときに全部直すことになります。 ここで Error に詰め替えておけば、画面側は err.message を出すだけで済みます。

3つめ。credentials: 'include' は、いまの構成では無くても動きますが、書いておきます。

fetch の credentials の既定値は same-origin で、同じオリジンへの要求ならセッションのクッキーは送られます。この記事は、開発中は Vite のプロキシ、本番は nginx で画面と API を同じオリジンにしているので、書き忘れても 401 にはなりません。include が要るのは、画面と API が別オリジンのとき(プロキシを使わずに http://192.168.226.50:3001 を直に呼ぶ場合など)です。API を別のドメインに分けたときに備えて書いておきます。

ルーティングを繋ぐ

~/hitokoto/web/src/main.jsx を丸ごと置き換えます。

import React from 'react'
import ReactDOM from 'react-dom/client'
import { BrowserRouter } from 'react-router-dom'
import './tokens.css'
import './index.css'
import App from './App.jsx'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>,
)

~/hitokoto/web/src/App.jsx を丸ごと置き換えます。

import { Routes, Route, NavLink } from 'react-router-dom'
import QuoteListPage from './pages/QuoteListPage'
import QuoteNewPage from './pages/QuoteNewPage'
import PublicQuotesPage from './pages/PublicQuotesPage'
import NotFoundPage from './pages/NotFoundPage'

export default function App() {
  return (
    <div className="app">
      <header className="app__header">
        <h1 className="app__title">hitokoto</h1>
        <nav aria-label="メインメニュー">
          <NavLink to="/">一覧</NavLink>
          <NavLink to="/new">登録</NavLink>
          <NavLink to="/public">公開</NavLink>
        </nav>
      </header>

      <main>
        <Routes>
          <Route path="/" element={<QuoteListPage />} />
          <Route path="/new" element={<QuoteNewPage />} />
          <Route path="/public" element={<PublicQuotesPage />} />
          <Route path="*" element={<NotFoundPage />} />
        </Routes>
      </main>
    </div>
  )
}

ルーティングの回から変わったところは2つだけです。

  • <Link> ではなく <NavLink> を使っています。いま開いている画面のリンクに、自動で active クラスが付きます。 「自分がどこにいるか」が分かるのは、地味ですが効きます
  • <nav> に aria-label を付けています。 読み上げソフトで「メインメニュー」と読まれます(アクセシビリティの回)

<Routes> の外にヘッダーがあるので、画面を移動してもヘッダーは消えません。 これも前回やったとおりです。

⑤ 「動く」と「使える」の差は、4つの状態

ここがこの記事の本体です。

一覧画面を、まず素直に書いてみます。多くの人が最初に書くのは、これです。

function QuoteListPage() {
  const [quotes, setQuotes] = useState([])

  useEffect(() => {
    api.listQuotes().then(setQuotes)
  }, [])

  return (
    <ul>
      {quotes.map((q) => <li key={q.id}>{q.body}</li>)}
    </ul>
  )
}

これは、動きます。 データがあれば、ちゃんと出ます。バグはありません。

では、次の3つの場面で、この画面はどう見えるでしょうか。

場面この画面の見た目
通信中の0.8秒真っ白
1件も登録していない人真っ白
サーバーが落ちている真っ白(Console だけにエラー)

3つとも、同じ見た目です。 「読み込んでいる」「まだ何も無い」「壊れている」は、使う人にとってまったく別のことなのに、画面上では区別が付きません。

「動く」と「使える」の差の正体は、ほとんどこれです。

4つの状態を、全部書く

1つの表示が取りうる状態は、4つあります。

状態いつ何を出すか
読み込み中要求を出してから、返事が来るまで待っていると分かるもの
エラー失敗した何が起きたか + 次にできること
空成功したが、0件だったこれから何をすればいいか
正常成功して、1件以上あったデータ

この順で判定します。 順番には意味があります。

~/hitokoto/web/src/pages/QuoteListPage.jsx を作ります。

import { useEffect, useState } from 'react'
import { Link } from 'react-router-dom'
import { api } from '../api/client'
import { Button } from '../components/Button'

export default function QuoteListPage() {
  const [status, setStatus] = useState('loading')
  const [quotes, setQuotes] = useState([])
  const [errorMessage, setErrorMessage] = useState('')

  async function load() {
    setStatus('loading')
    try {
      const data = await api.listQuotes()
      setQuotes(data.quotes ?? [])
      setStatus('done')
    } catch (err) {
      setErrorMessage(err.message)
      setStatus('error')
    }
  }

  useEffect(() => {
    load()
  }, [])

  if (status === 'loading') {
    return <p className="state" role="status">読み込んでいます…</p>
  }

  if (status === 'error') {
    return (
      <div className="state state--error" role="alert">
        <p>一覧を読み込めませんでした。</p>
        <p className="state__detail">{errorMessage}</p>
        <Button onClick={load}>もう一度読み込む</Button>
      </div>
    )
  }

  if (quotes.length === 0) {
    return (
      <div className="state">
        <p>まだ1件も登録されていません。</p>
        <p className="state__detail">
          読んだ本の中で、心に残った一文を1つだけ書き留めるところから始めます。
        </p>
        <Link className="btn btn--primary btn--md" to="/new">最初の一文を登録する</Link>
      </div>
    )
  }

  return (
    <ul className="quote-list">
      {quotes.map((q) => (
        <li key={q.id} className="quote">
          <blockquote className="quote__body">{q.body}</blockquote>
          <p className="quote__meta">{q.book_title}{q.page ? ` p.${q.page}` : ''}</p>
        </li>
      ))}
    </ul>
  )
}

長く見えますが、増えたのは「正常以外の3つ」だけです。

なぜ、この順番なのか

「空」の判定を、status === 'done' の後ろに置いているのが重要です。

if (status === 'loading') { ... }   // 1
if (status === 'error')   { ... }   // 2
if (quotes.length === 0)  { ... }   // 3 ← 成功したことが確定してから

逆にすると、事故ります。 quotes の初期値は [] なので、読み込み中も length === 0 です。先に空の判定を書くと、通信中に「まだ1件もありません」と言い切ってしまいます。

「0件」と「まだ分からない」は、別のことです。 [] は、その2つを区別できません。 だから状態を別の変数(status)で持ちます。

一番忘れるのは「空っぽ」です

4つのうち、実務でいちばん抜け落ちるのは「空」です。 理由がはっきりしています。

開発している自分の環境には、テスト用のデータが必ず入っているからです。

あなたは開発中、何度も一覧画面を開きます。そのたびに、自分が入れた10件が表示されます。 空の画面を見る機会が、ほぼありません。

一方、この画面を初めて開く人は、必ず0件です。

開発者が最も見ない画面が、使う人が最初に必ず見る画面です。

だから、空状態には「0件です」と書いてはいけません。

書き方使う人が受け取るもの
該当するデータはありません壊れているのか、そういうものなのか分からない
まだ1件も登録されていません + 登録画面へのボタン正常だと分かり、次に何をすればいいかも分かる

空状態は、エラー表示ではありません。 アプリの使い方を教える、たった1回のチャンスです。

確かめ方は簡単です。データベースから自分の行を消してみるか、まっさらな新規ユーザーでログインします。

bash
$ mysql -u hitokoto -p hitokoto -e "select count(*) from quotes;"

[スクリーンショット: 03_空状態.png] 1件も登録していない状態で一覧画面を開き、「まだ1件も登録されていません」と登録ボタンが出ているところを撮ってください。

エラー状態は「戻れる」ようにする

エラー画面で一番やってはいけないのは、行き止まりにすることです。

<Button onClick={load}>もう一度読み込む</Button>

この1行があるかないかで、使えるかどうかが変わります。 無いと、使う人にできることはブラウザのリロードだけになります。書いた本人は「リロードすればいい」と思っていますが、使う人はそう思いません。

role="alert" と role="status" も、飾りではありません。

属性読み上げソフトの挙動
role="status"今読んでいるところを邪魔せずに、後から伝える(読み込み中に向く)
role="alert"すぐに割り込んで読む(エラーに向く)

画面が切り替わったことは、目で見ている人にしか伝わりません。 アクセシビリティの回でやった話が、ここで実際に必要になります。

わざと壊して、4つ全部を見る

書いたら、必ず4つとも目で見てください。 見ないと、書いたつもりで書けていません。

見たい状態起こし方
読み込み中開発者ツールの Network タブで Throttling を「Slow 4G」にしてリロード
エラーExpress を Ctrl+C で止めてリロード
空quotes テーブルを空にする、または新規ユーザーで入る
正常2〜3件登録する

[スクリーンショット: 04_エラー状態.png] Express を止めた状態で一覧を開き、「一覧を読み込めませんでした」と再読み込みボタンが出ているところを撮ってください。

エラーを起こす手段を、自分で持っておくこと自体が成果です。 障害対応の回でやった「わざと壊す」を、画面でもやっているだけです。

⑥ フォームの作法

登録画面を作ります。フォームは、一覧より事故が多いです。書き込みが起きるからです。

~/hitokoto/web/src/pages/QuoteNewPage.jsx を作ります。

import { useEffect, useState } from 'react'
import { useNavigate } from 'react-router-dom'
import { api } from '../api/client'
import { Button } from '../components/Button'

export default function QuoteNewPage() {
  const navigate = useNavigate()
  const [books, setBooks] = useState([])
  const [bookId, setBookId] = useState('')
  const [body, setBody] = useState('')
  const [page, setPage] = useState('')
  const [submitting, setSubmitting] = useState(false)
  const [errorMessage, setErrorMessage] = useState('')

  useEffect(() => {
    api.listBooks()
      .then((data) => setBooks(data ?? []))
      .catch((err) => setErrorMessage(err.message))
  }, [])

  async function handleSubmit(event) {
    event.preventDefault()
    if (submitting) return

    setErrorMessage('')
    setSubmitting(true)
    try {
      await api.createQuote({
        book_id: Number(bookId),
        body: body.trim(),
        page: page === '' ? null : Number(page),
      })
      navigate('/')
    } catch (err) {
      setErrorMessage(err.message)
    } finally {
      setSubmitting(false)
    }
  }

  return (
    <form className="form" onSubmit={handleSubmit} noValidate>
      <h2>一文を登録する</h2>

      {errorMessage && (
        <p className="form__error" role="alert">{errorMessage}</p>
      )}

      <div className="field">
        <label htmlFor="book">本</label>
        <select
          id="book"
          value={bookId}
          onChange={(e) => setBookId(e.target.value)}
          required
        >
          <option value="">選んでください</option>
          {books.map((b) => (
            <option key={b.id} value={b.id}>{b.title}</option>
          ))}
        </select>
      </div>

      <div className="field">
        <label htmlFor="body">引用する一文</label>
        <textarea
          id="body"
          rows={4}
          value={body}
          onChange={(e) => setBody(e.target.value)}
          required
        />
        <p className="field__hint">{body.length} / 300 文字</p>
      </div>

      <div className="field">
        <label htmlFor="page">ページ(任意)</label>
        <input
          id="page"
          type="number"
          inputMode="numeric"
          value={page}
          onChange={(e) => setPage(e.target.value)}
        />
      </div>

      <Button type="submit" disabled={submitting}>
        {submitting ? '保存しています…' : '保存する'}
      </Button>
    </form>
  )
}

このフォームで守っていることが4つあります。1つずつ、なぜ必要かを書きます。

1. 送信中は、ボタンを止める

if (submitting) return
// ...
<Button type="submit" disabled={submitting}>

二重送信を止めています。

開発中の自分の環境では、保存が一瞬で終わります。 だから2回押しません。本番で、回線が遅い人が「反応が無いな」と思ってもう1回押します。 同じ一文が2件登録されます。

disabled で二重送信は止まります。 if (submitting) return は念のための保険です。 ただし、ボタンを押してから React が再描画するまでの間にもう1回呼ばれた場合、その時点の submitting はまだ false のまま読まれる(state はその描画のときの値)ので、この1行では止まりません。確実にしたいなら useRef でフラグを持ちます。両方書きます。

そして、disabled にするだけでなく、ラベルも変えます。

{submitting ? '保存しています…' : '保存する'}

押せないボタンが押せない理由が、書いていなければ伝わりません。 灰色になっているだけだと、「壊れた」と読まれます。

2. 失敗しても、入力を消さない

catch の中を見てください。 setBody('') を書いていません。

これは意図的です。

保存に失敗したときに入力欄を空にするのは、最悪の裏切りです。 300文字書いた人が、サーバー側のちょっとした検証エラーで、全部失います。

navigate('/') は try の中、成功した後ろにしか置いていません。 成功したときだけ画面を移ります。

これは、書き忘れるというより「気を利かせて消してしまう」ほうが多い間違いです。「フォームをきれいにしておこう」と思ってしまうからです。入力データは、使う人が作ったものです。勝手に捨てません。

3. どこが悪いかを出す

{errorMessage} を <form> の先頭に置いています。

サーバーは { error: { code, message } } で返してくるので、「本文は必須です」がそのまま出ます。 ここで、client.js でエラーの形を1回だけ翻訳しておいた効果が出ます。

やってはいけないのは、これです。

alert('エラーが発生しました')
何が伝わるか
エラーが発生しました何も伝わらない。 直しようがない
本文は必須ですどこを直せばいいか分かる

role="alert" を付けているので、読み上げソフトにも届きます。

4. <label> を必ず htmlFor で結ぶ

<label htmlFor="body">引用する一文</label>
<textarea id="body" ... />

これは見た目の話ではありません。3つのことが同時に起きます。

  • ラベルの文字をクリックすると、入力欄にフォーカスが入る(指で触るスマホで効きます)
  • 読み上げソフトが「引用する一文、編集テキスト」と読む。結んでいないと「編集テキスト」としか読みません
  • id が無いと、そもそも結べない

アクセシビリティの回でやったことの、そのままの回収です。理屈を知っていても、自分のフォームで書くのは別なので、ここで書きます。

noValidate を付けているのはなぜか。 ブラウザ標準の検証メッセージは、言語もデザインも制御できません。 required は残して(読み上げソフトが「必須」と読むため)、表示だけは自分の errorMessage に寄せています。

[スクリーンショット: 05_送信中のボタン.png] 保存ボタンを押した直後、「保存しています…」に変わって押せなくなっている状態を撮ってください。Network タブで Throttling を効かせると撮りやすいです。

⑦ デザインを、新しく決めない

ここで、前回のデザインシステムの回が回収されます。

やることは、コピーだけです。

bash
$ cp ~/react-demo/src/tokens.css ~/hitokoto/web/src/tokens.css
$ mkdir -p ~/hitokoto/web/src/components
$ cp ~/react-demo/src/components/Button.jsx ~/hitokoto/web/src/components/
$ cp ~/react-demo/src/components/Button.css ~/hitokoto/web/src/components/

main.jsx の先頭で import './tokens.css' を読み込んでいるので、これで使えます。

ここで我慢することが1つあります。

新しい色を1つも決めません。

新しいアプリを作ると、「このアプリの色を決めたい」という気持ちが必ず出ます。引用のアプリだから落ち着いた色にしたい、とか。

それをやると、--color-primary が2種類になります。 そして3か月後、どちらが正しいのか分からなくなります。 前回の記事で書いた「毎回その場で決め直す」に、まっすぐ戻ります。

色を変えたくなったら、tokens.css の値を書き換えます。 アプリ側に新しい色を書き足すのではありません。 それがトークンを作った理由です。

足りない部分だけ、CSSを書きます。 ~/hitokoto/web/src/index.css を丸ごと置き換えます。

* { box-sizing: border-box; }

body {
  margin: 0;
  color: var(--color-text);
  background: var(--color-surface);
  font-family: system-ui, sans-serif;
  line-height: 1.7;
}

.app {
  max-width: 720px;
  margin: 0 auto;
  padding: var(--space-4);
}

.app__header {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-4);
  align-items: baseline;
  border-bottom: 1px solid var(--color-border);
  padding-bottom: var(--space-3);
}

.app__title { font-size: var(--font-size-lg); margin: 0; }

.app__header nav { display: flex; gap: var(--space-4); }
.app__header a { color: var(--color-text-muted); text-decoration: none; }
.app__header a.active {
  color: var(--color-primary);
  border-bottom: 2px solid var(--color-primary);
}

.state {
  padding: var(--space-6) var(--space-4);
  text-align: center;
  color: var(--color-text-muted);
}
.state--error { color: var(--color-danger); }
.state__detail { font-size: var(--font-size-sm); }

.quote-list { list-style: none; padding: 0; }
.quote {
  border-bottom: 1px solid var(--color-border);
  padding: var(--space-4) 0;
}
.quote__body {
  margin: 0;
  font-size: var(--font-size-md);
  border-left: 3px solid var(--color-border);
  padding-left: var(--space-3);
}
.quote__meta {
  margin: var(--space-2) 0 0;
  font-size: var(--font-size-sm);
  color: var(--color-text-muted);
}

.form { display: flex; flex-direction: column; gap: var(--space-4); max-width: 100%; }
.field { display: flex; flex-direction: column; gap: var(--space-1); }
.field label { font-size: var(--font-size-sm); color: var(--color-text-muted); }
.field input,
.field select,
.field textarea {
  font-family: inherit;
  font-size: var(--font-size-md);
  padding: var(--space-2);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-sm);
  max-width: 100%;
}
.field__hint { margin: 0; font-size: var(--font-size-sm); color: var(--color-text-muted); }
.form__error { color: var(--color-danger); margin: 0; }

数字が直接書いてあるのは max-width: 720px と line-height と枠線の 1px だけです。余白・色・文字サイズは、全部トークンから来ています。

⑧ アクセシビリティの最低線

ここは「頑張るところ」ではなく、「これだけは外さない」を確認するところです。確認は3分で終わります。

マウスから手を離して、Tab キーだけで一周してください。

確認すること落ちていたら
Tab で全部の操作にたどり着けるかどこかに <div onClick> がある。<button> に直す
いまどこにいるか、輪郭で見えるかどこかに outline: none がある。消す
Enter / Space でボタンが押せるか同上。<button> なら勝手に効きます
Tab の順番が、見た目の順番と合っているかCSS で並べ替えている。HTMLの順番を直す

この記事のコードは、この4つを満たしています。 意識して満たしたのではなく、<button> <form> <label> <nav> という素のHTMLを使ったから、自動的にそうなっているだけです。

アクセシビリティ対応の大半は、「追加でやること」ではなく「壊さないこと」です。 <div> でボタンを作らなければ、直す作業は発生しません。

もう1つだけ、確認します。

開発者ツールの Lighthouse で Accessibility を1回だけ回してください。 点数を上げるのが目的ではありません。 <label> の付け忘れと、コントラスト不足を機械的に拾うためだけに使います。90点台なら十分です。

[スクリーンショット: 06_キーボード操作.png] Tab キーで保存ボタンにフォーカスが当たり、青い輪郭が出ているところを撮ってください。

⑨ スマホで見る

レスポンシブの回の回収です。 1つだけ、必ず確認します。

~/hitokoto/web/index.html の <head> に、この行があるか見てください。Vite の初期テンプレートには入っています。

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

これが無いと、以降の CSS が全部無駄になります。 スマホが勝手に「980px幅のPC画面」として描画して、全体を縮小するからです。

確認のしかたは2つ。

1つめ。開発者ツールで見る。 F12 → デバイスツールバー(Ctrl+Shift+M)→ 幅を 375px にします。

見るのは1点だけです。横スクロールバーが出ていないこと。

document.documentElement.scrollWidth > document.documentElement.clientWidth

Console でこれを打って false が返れば、はみ出していません。

2つめ。実機で開く。 スマホをVMと同じネットワークに繋いで、http://192.168.226.50:5173/ を開きます。

実機とDevToolsは、同じではありません。 DevToolsで分からないのは、指の太さです。ボタンが小さすぎて押しにくいは、実機でしか分かりません。目安は44px四方です。 .btn--md は padding: var(--space-2) var(--space-4) なので、文字の高さと合わせて40px前後です。スマホ用に --space-3 に上げるかは、実機で押してから決めます。

この記事の CSS が、はみ出しを防いでいるところは3つです。

  • .app { max-width: 720px; } — width で固定していません。 画面が狭ければ狭いまま入ります
  • .app__header { flex-wrap: wrap; } — 狭くなったらタイトルとメニューが2段に折り返します
  • .field input { max-width: 100%; } — <input> は放っておくと既定の幅を持っていて、はみ出します

[スクリーンショット: 07_スマホ幅.png] デバイスツールバーで幅375pxにした一覧画面を撮ってください。横スクロールバーが出ていないことが分かる形で。

⑩ 本番の形で確認する

ここをやらずに終わると、この記事は失敗です。

いまの状態は、Vite の開発サーバーがある前提でしか動きません。 プロキシも、そこにしか書いていません。

「自分のPCでは動きます」の正体は、たいていこれです。

本番の形はこうです。

開発中(いま)本番の形
画面Vite 開発サーバー(5173)dist/ の静的ファイルを nginx が配る
/apiVite がプロキシnginx がプロキシ
ポート5173 と 300180 だけ

ビルドする

bash
$ cd ~/hitokoto/web
$ npm run build
$ ls dist
assets  index.html  vite.svg

dist/ の中身が何なのかは、ビルドツールの回でやったとおりです。JSX も import も残っていない、ブラウザがそのまま読める形になっています。

nginx に配らせる

bash
$ sudo mkdir -p /var/www/hitokoto
$ sudo cp -r ~/hitokoto/web/dist/* /var/www/hitokoto/
$ sudo nano /etc/nginx/sites-available/hitokoto
server {
    listen 80;
    server_name _;

    root /var/www/hitokoto;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

この設定に、新しいものは1つもありません。

Vite の server.proxy に書いたことと、まったく同じことを、nginx が本番でやります。だから、画面のコードは1文字も変えなくて済みます。 fetch('/api/quotes') のままです。

server.proxy を「開発用の逃げ道」ではなく「本番と同じ形の予行演習」にしておいた効果が、ここで出ます。 http://192.168.226.50:3001/api/... と直に書いていたら、ここで全部書き換えることになっていました。

有効にして、確かめます。

bash
$ sudo ln -s /etc/nginx/sites-available/hitokoto /etc/nginx/sites-enabled/
$ sudo rm -f /etc/nginx/sites-enabled/default
$ sudo nginx -t
$ sudo systemctl reload nginx

nginx -t が syntax is ok と test is successful を返してから reload します。 逆順にすると、設定が壊れていたときに nginx が上がらなくなります(nginxの回)。

Vite の開発サーバーを止めてから、ブラウザで http://192.168.226.50/ を開いてください。ポート番号なしです。

確認するのは3つ。

  1. 一覧が出ること(/api のプロキシが効いている)
  2. http://192.168.226.50/new を、リンクではなくアドレスバーに直接打って開けること(try_files が効いている)
  3. 開発者ツールの Network で、/api/quotes の要求先が 192.168.226.50 になっていること(3001番が出てこない)

[スクリーンショット: 08_本番の形.png] http://<VMのIP>/ を開き、ポート番号なしで一覧が表示されている画面を撮ってください。アドレスバーが読める形で。

戻し方: うまくいかなければ、sudo rm /etc/nginx/sites-enabled/hitokoto して sudo systemctl reload nginx で元に戻せます。dist/ を作り直したいときは、npm run build からやり直すだけです。dist/ は生成物なので、消しても失われるものはありません。

⑪ ここでやらないと決めたこと

動くようになると、手を止めるのが難しくなります。 先に、やらないものを書いておきます。

やりたくなることいまやらない理由
アニメーション4つの状態が全部書けてから。動きは「使える」を上げません。むしろ、読み込み中の演出が本物の遅さを隠します
ダークモードトークンがあるので後からできます。いまやると、確認する画面が2倍になります
無限スクロール10件しか無いうちは、ただの複雑さです。「もっと見る」ボタンで足ります
楽観的更新先に画面を更新して、失敗したら戻す。戻す処理を正しく書くのは難しいです。待たせるほうが、いまは正しい
状態管理ライブラリ状態管理の回でやったとおり、バケツリレーが辛くなってからです。3画面では辛くなりません
TypeScript化型の回でやりました。後から入れられます。動くものを先に完成させます

完成しないアプリの最大の原因は、難しさではなく、途中で別のことを始めることです。

この記事の範囲は「3画面が、4つの状態を持って、本番の形で動く」までです。そこで止めます。

つまずいたところ

実際に詰まった順に書きます。

1. credentials: 'include' が無いとクッキーが送られない、と思い込んでいた。

fetch はクッキーを既定で送らない、と思い込んで include を足しました。実際の既定値は same-origin で、プロキシ越しの同一オリジンなら、書かなくてもクッキーは送られます。 どちらなのかは、Network タブで要求ヘッダに Cookie が付いているかを見ればすぐ確かめられます。include が本当に要るのは別オリジンに投げるときで、そのときはサーバー側の CORS でも資格情報(Access-Control-Allow-Credentials)を許可する必要があります。

2. 「まだ1件も登録されていません」が、一瞬だけ光った。

status を使わず quotes.length === 0 だけで判定していたときです。読み込み中も [] なので、通信が終わるまで空状態が出ていました。 データがある人にまで「まだ1件もありません」が0.5秒表示されます。これで、状態を別の変数で持つ理由が腹に落ちました。

3. vite.config.js を直したのに、CORS が消えなかった。

Vite を再起動していませんでした。 ソースコードはホットリロードされますが、設定ファイルは起動時にしか読まれません。 「設定を書いたのに効かない」の半分くらいは、これだと思います。

4. ビルドしたら真っ白になり、Console に Unexpected token '<' が出た。

try_files を書かずに location / で全部 index.html を返していました。JavaScript を要求したのに HTML が返ってきていたということです。ルーティングの回で「こうなる」と読んで知っていたのに、自分で同じことをやりました。 読んで知っていることと、書けることは別でした。

5. スマホの実機で、保存ボタンが押しにくかった。

DevTools の375px幅では何の問題もありませんでした。指で押すと、隣の「ページ」入力欄に当たりました。 ボタンの高さが足りていませんでした。--space-3 に上げて解決しましたが、これは実機を触るまで一度も気づきませんでした。

6. エラーメッセージが「[object Object]」になった。

err.message ではなく、エラーオブジェクトをそのまま {errorMessage} に入れていました。React は文字列以外を素直に描画しません。 client.js で Error に詰め替える形にしたのは、この事故がきっかけです。

まとめ

この記事で理解できたこと。

  • 画面の「完成」は、コードが動くことではない。 バグがゼロでも、真っ白な画面は使えない
  • 1つの表示には状態が4つある。 読み込み中 / エラー / 空 / 正常。 正常だけ書くと、残り3つは「真っ白」という同じ見た目に潰れて、区別が付かなくなる
  • 判定の順番に意味がある。 [] は「0件」と「まだ分からない」を区別できないので、状態は別の変数で持つ
  • 一番忘れるのは「空」。 開発者が最も見ない画面が、使う人が最初に必ず見る画面だから。空状態は「0件です」ではなく「次に何をすればいいか」を書く場所
  • フォームで守るのは3つ。 送信中は止める(二重送信)/失敗しても入力を消さない(人が作ったデータを捨てない)/どこが悪いか出す(「エラーが発生しました」は何も伝えない)
  • デザインは決め直さない。 トークンと Button をコピーして使う。新しいアプリだからといって、新しい色を1つも決めない
  • アクセシビリティの大半は「追加でやること」ではなく「壊さないこと」。 <button> <form> <label> を素直に使えば、Tab キーだけで一周できる
  • 開発サーバーでしか動かない状態で終わらない。 server.proxy を「同じオリジンに見せる」形にしておくと、nginx の proxy_pass にそのまま置き換わり、画面のコードは1文字も変わらない

そして、いちばん大きいのはこれです。

「動く」から「使える」までの距離は、新しい技術ではなく、書き足す分量で埋まります。 一覧画面のコードは10行から45行に増えました。増えた35行は、全部「正常ではないとき」の話です。

参考リンク


次に読む

この記事は 【第9段階】作品を1つ完成させる の 3 / 10 本目です。

記事
← 前の記事全部書いてから動かさない — 作品のAPIと認証
→ 次の記事公開の前に、戻せることを確かめる — デプロイと運用の入口

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

作品づくり。使う技術は第0〜第8段階で扱ったものだけ。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次