「動く」と「使える」の差は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つも足さない
この記事でやること
~/hitokoto/webを Vite で作り、server.proxyで/apiをバックエンドに転送してCORSを消す- 画面を3枚だけ作る(一覧 / 登録 / 公開ページ)。ルーティングで繋ぐ
- 一覧画面に、4つの状態(読み込み中・空・エラー・正常)を全部書く
- 登録フォームを「壊れない」形にする(送信中はボタンを止める / 失敗しても入力を消さない / どこが悪いか出す)
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の中で打ちます。
-- の後ろが npm create ではなく、その先の道具に渡る引数です。npmの回でやった npm run dev -- --host と同じ書き方です。
続けて依存を入れます。
確認します。
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は別のファイルのままにします。 依存が混ざると、「ブラウザに送るコードの中に、データベース接続のライブラリが紛れ込む」ことが起こり得ます。 フォルダは同じ、依存は別です。
動くことだけ先に確認する
--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 を丸ごと置き換えます。
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 を再起動します。
ブラウザで 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 を散らかさないためです。
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回のチャンスです。
確かめ方は簡単です。データベースから自分の行を消してみるか、まっさらな新規ユーザーでログインします。
[スクリーンショット: 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 を効かせると撮りやすいです。
⑦ デザインを、新しく決めない
ここで、前回のデザインシステムの回が回収されます。
やることは、コピーだけです。
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 が配る |
/api | Vite がプロキシ | nginx がプロキシ |
| ポート | 5173 と 3001 | 80 だけ |
ビルドする
assets index.html vite.svg
dist/ の中身が何なのかは、ビルドツールの回でやったとおりです。JSX も import も残っていない、ブラウザがそのまま読める形になっています。
nginx に配らせる
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つもありません。
try_files $uri $uri/ /index.html;— ルーティングの回でやった、/newを直接開いたときの404を防ぐ1行ですlocation /api/のproxy_pass— リバースプロキシの回でやった、ポート番号を隠すやつです
Vite の server.proxy に書いたことと、まったく同じことを、nginx が本番でやります。だから、画面のコードは1文字も変えなくて済みます。 fetch('/api/quotes') のままです。
server.proxyを「開発用の逃げ道」ではなく「本番と同じ形の予行演習」にしておいた効果が、ここで出ます。http://192.168.226.50:3001/api/...と直に書いていたら、ここで全部書き換えることになっていました。
有効にして、確かめます。
nginx -t が syntax is ok と test is successful を返してから reload します。 逆順にすると、設定が壊れていたときに nginx が上がらなくなります(nginxの回)。
Vite の開発サーバーを止めてから、ブラウザで http://192.168.226.50/ を開いてください。ポート番号なしです。
確認するのは3つ。
- 一覧が出ること(
/apiのプロキシが効いている) http://192.168.226.50/newを、リンクではなくアドレスバーに直接打って開けること(try_filesが効いている)- 開発者ツールの 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行は、全部「正常ではないとき」の話です。
参考リンク
- roadmap.sh — Frontend Developer
- roadmap.sh — Full Stack Developer
- Vite — Server Options
- Vite — Building for Production
- React 公式 — You Might Not Need an Effect
- React 公式 — Reacting to Input with State
- MDN — CORS
- MDN — fetch の credentials
- MDN — label 要素
- WAI-ARIA — alert ロール
- nginx — try_files
- nginx — proxy_pass
次に読む
この記事は 【第9段階】作品を1つ完成させる の 3 / 10 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | 全部書いてから動かさない — 作品のAPIと認証 |
| → 次の記事 | 公開の前に、戻せることを確かめる — デプロイと運用の入口 |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
作品づくり。使う技術は第0〜第8段階で扱ったものだけ。

コメント