TOEIC語彙ラボ is a comprehensive web application for learning essential TOEIC vocabulary, featuring AI-generated explanations, pronunciation support, and efficient caching strategies.
-
Content Error Reports and Social Metadata: Every available word explanation includes an email report link with the word and canonical URL prefilled, plus a contact-page fallback. Home Open Graph and Twitter titles/descriptions match its page metadata and retain share images. robots.txt keeps crawl rules and the sitemap URL without the unused Host directive. (Updated: 2026-10-02)
-
Study Audio Controls: Study/review word and example-sentence audio buttons use 44×44px targets, 20px icons, blue styling, and visible keyboard focus. The example button sits beside the sentence instead of inline, so wrapped sentences keep even line spacing.
-
Consistent Difficulty Labels: Level UI uses 最重要 / 中級 / 上級 and shared blue / violet / rose styles across home, search, daily picks, and word details. Labels, score guidance, and styling come from the shared level definitions.
-
Accessible Favorites Confirmation: Clear-all uses a native modal dialog with initial focus on Cancel, Escape dismissal, and browser-managed background interaction blocking. Cancel restores focus to the trigger; successful deletion focuses the empty-state message.
-
Inline Audio Recovery: Word details and study/review cards show audio fetch/playback errors near the affected control with an explicit retry button. New playback clears the error; stale requests are ignored after switching audio, cards, or pages. Study word requests use the canonical slug (including uppercase terms such as CEO), and scope changes clear loading/error/retry state so revisiting a card remains playable.
-
Consistent Term Search: Home, all-words, and favorites share NFKC/case/whitespace normalization and exact-match-first prefix ordering. Home and all-words also share * wildcard matching, including full-width ＊; favorites retain prefix-only search.
-
Home Search Recovery: Empty word-search results show spelling/prefix guidance, a clear button that restores input focus and the first page, and a link to the meaning-search tab. (Updated: 2026-09-26)
-
Initial-load resources: The UI uses system fonts without Geist downloads/preloads. A8 banners and their tracking pixels use native lazy loading, retaining their dimensions to reserve layout space.
-
Curated Word Lists: Access 1,300+ important TOEIC vocabulary words classified into three levels (Important / Medium / High), sourced from Vercel Blob in production. Blob fetch failures throw (instead of returning an empty list) so a transient outage never gets cached as an empty word list — the last good cache keeps serving.
-
SEO-Optimized Learning Hub: /words combines a score/letter/prefix search explorer with a server-rendered complete index. The complete index keeps every word available through a crawlable <a href> while nesting level → initial-letter groups in native <details> disclosure panels, so the mobile page is scannable without sacrificing the internal-link graph.
-
Google Search Site Name: Google-facing site-name signals use TOEIC語彙ラボ (WebSite.name, og:site_name, and application-name), while page titles keep the established TOEIC重要単語 product name. The homepage uses the factual 2026年版 label rather than claiming unverified “latest test trends.”
-
Snappy List → Detail Navigation: Word links use prefetch={false} (Vercel Edge Request reduction) and the detail route is fully SSG, which together cause the static RSC payload to render with the Suspense boundary already resolved (so loading.tsx never visibly fires). Interactive explorer cards wrap WordLinkPending (useLinkStatus) for instant click feedback; the 1,300+ links in the complete SEO index remain plain Server Component links to avoid creating a client boundary for every word.
-
AI-Powered Explanations: Detailed definitions, synonyms, and examples generated by Google Gemini (gemini-2.5-flash-lite).
-
Adaptive Word-Detail Disclosures: A word's primary Japanese translation always stays visible, while dense supporting content can be collapsed. Every native <details> panel is expanded on initial page display and starts with an explicit 「閉じる」action; after the user closes one, its one-line preview, item count, and 「見る」action keep the hidden content discoverable. Short sections remain permanently visible without adding an unnecessary interaction. The pure length/count rules live in src/lib/word-detail-disclosure.ts and keep the behavior consistent across AI-generated payloads.
-
Smart Caching:
- L1: Next.js Data Cache (
"use cache" + cacheLife("max"), revalidated on demand via /api/revalidate/*) for instant access.
- L2: Upstash Redis for persistent, shared caching across users.
- L3: On-demand AI generation for missing words.
-
Semantic Search（意味で探す）: The /words explorer has a second search tab that finds words by meaning — Japanese queries like「延期する」or「感謝を伝えるメールで使う単語」work. Each word's AI-generated WordDetails (definitions, synonyms, examples) is embedded as one document with gemini-embedding-001 (768 dims, L2-normalized) and stored in Upstash Vector; queries are embedded the same way and matched via cosine top-K (POST /api/search/semantic). Candidates below the configurable similarity threshold (default 0.82) are omitted. Results are cached in Redis for 7 days using both the normalized-query hash and a Vector-index generation; bulk or per-word vector updates advance the generation so stale results stop being addressable immediately. Requests are rate-limited per IP and results link straight to /words/[slug]. The TOP page has a lightweight launcher card (SemanticSearchLauncher, titled「意味で探す」and placed below the daily picks, above the spelling-based word list) that transfers the query through same-tab sessionStorage and navigates with only an opaque launch ID (/words?mode=meaning&launch=...#word-explorer). The query text therefore stays out of Vercel request URLs and GA4 page_location; GA4 custom events also receive only query length, never the text. useSearchParams keeps the explorer synchronized with browser history, while an in-flight request map prevents React Strict Mode from issuing duplicate semantic-search requests.
-
Study Modes:
- List View: Browse words by level (Important / Medium / High), initial letter, prefix, and wildcard (
*) search. /words initially renders 36 compact result cards with “load more”, while the complete A–Z index stays available below.
- Study Mode: Flashcard-style learning. The front shows the word (with pronunciation audio and an optional example-sentence hint); “答えを見る” reveals the Japanese meaning, parts of speech, and an example with its translation, and only then can the learner grade it Remembered / Not Remembered / Later (the same button order as before). Grading unlocks only once the answer has loaded; if it fails to load, only Later and a retry stay available. Every grade advances to the next card on the same screen; the answer links to the full word detail. An in-session "review later" sidebar keeps deferred words.
- Review Mode (Sign-In Required): Focus on words marked as favorites. Guests reaching
/review — including by bookmark — get the shared FavoritePracticeLoginGate instead of a session; there is no guest fallback to the full favorites list.
-
Today’s 6 Picks:
- A compact “今日おすすめの6単語” section is shown on the TOP page.
- All 6 words are displayed directly in the TOP section without a separate “view all” button.
- Picks are determined by UTC date key + word slug hash, so the same day yields the same 6 words.
- Selection logic lives server-side in
getTodayRecommendedSelection() as a Cache Component ('use cache' + cacheLife('max')), which returns the picks together with their date key and an 8-character word-corpus version. The cache entry is tagged with both today-recommended-words and word-list, so a word-list revalidation also marks the derived daily selection stale. TOP / /today-words / /today-words/listen receive the same cached 6 words, refreshed once per day at JST 7:05 (UTC 22:05) via Vercel Cron (/api/revalidate/today-words). The pick count is the shared constant TODAY_WORDS_COUNT. getTodayRecommendedWords() is a thin uncached wrapper for callers that only need the words — the cache boundary stays on the selection function so there is only ever one cache entry.
- On the TOP page, the daily picks, word-list/stat block, and FAQ block are each rendered behind their own
<Suspense> boundary. The page shell no longer awaits the full word list before streaming, and each async block has a stable skeleton fallback to reduce layout shift.
- Because
cacheLife('max') never self-expires, the daily rotation depends solely on the Vercel Cron firing; the cron should be monitored, since a stalled cron freezes the same 6 words indefinitely. A time-based fallback ('days') is intentionally not combined with it to avoid double revalidation.
- Word-detail navigation never calls the daily cache. Daily-picks links carry the displayed slug order as a JSON
picks query. resolveTodayNavigation() validates the bounded, unique list against known words and preserves it through every previous/next link, even when the cached corpus version differs. Invalid or unavailable selections hide both navigation links and offer a return to /today-words; they never widen to the full word list. Valid legacy date/version links are upgraded to snapshots. No daily cache dependency is added to pre-rendered word pages.
-
Listen-and-Repeat Mode (Beta) (/today-words/listen — open to everyone, /favorites/listen — sign-in required):
- Hands-free auto-play of today's 6 words or favorite words: each word is read out as word → English example → Japanese example, then advances to the next word.
FavoritesListenClient is a thin state gate (guest → login gate, loading → skeleton, error → retry) and mounts FavoritesListenPlayer only once Supabase favorites are ready, so no TTS request is issued for a signed-out visitor.- Play / Pause / Skip-Prev / Skip-Next controls. A completion message is shown after the final selected word; pressing play again restarts from the top.
- Internally, audio sequencing uses a ref-based state machine to guard against
onended race conditions, and prefetches the current and next word's WordDetails for instant example previews.
-
Favorites: Save difficult words for later review. Persisted in local storage via FavoritesContext for guests; synced to Supabase for signed-in users. Adding and browsing favorites never requires an account; only the favorites-powered review and listen modes do. On /favorites, signed-out visitors with at least one favorite see FavoritePracticeLoginCard (a single card linking to /login?next=/mypage) in place of the review/listen buttons.
/favorites has a prefix search box that filters the list by English term. Matching lives in the pure, unit-tested src/lib/word-search.ts (filterWordsByTermPrefix): input is NFKC-normalized, whitespace-collapsed, trimmed, and lowercased so full-width IME input still matches; exact matches come first and the newest-first order is otherwise kept. Substring and wildcard (*) matching are intentionally not supported here. The query never enters the URL or analytics. The bulk-delete button is labeled 「すべて削除」 so it is not mistaken for clearing the search, and it still removes every favorite behind the existing confirmation modal.- Local storage is subscribed to as an external store (
src/lib/favorites-store.ts + useSyncExternalStore) rather than being loaded through a mount effect, so no setState happens inside an effect and SSR/hydration stays consistent via getServerSnapshot(). If browser storage is unavailable, an in-memory fallback keeps favorites usable for the current tab.
- Remote favorites are tagged with both the user ID and an authentication epoch. This prevents stale Supabase state from an earlier login from hiding or overwriting favorites added while signed out, even when the same account signs back in and the refresh request fails.
-
Optional Sign-In & Favorites Sync (Supabase): Google sign-in (/login) stays optional for the core experience — browsing, search, favorites (add/list), Study Mode, and the daily picks all work without an account. The favorites-powered review and listen modes and My Page require sign-in. The login page provides a TOP-page return button in both signed-in and signed-out states. While LOGIN_MAINTENANCE in src/lib/auth-maintenance.ts is true, signed-out visitors see a maintenance notice instead of the Google button and existing sessions keep working (see §10 of docs/operations/phase1-login-favorites-sync-setup.md). The TOP header uses one authentication control: it shows ログイン while signed out and automatically becomes マイページ after authentication, with sign-out beside it instead of rendering a separate “logged in” badge and duplicate My Page button. The login link keeps prefetch={false} and uses useLinkStatus for immediate inline feedback; /login/loading.tsx and the page-level <Suspense> boundary reuse a stable login-card skeleton through route loading, hydration, and the initial auth check. Signing in stores favorites in Supabase Postgres (RLS-protected favorites table) so they sync across devices. On first login, locally stored favorites are merged into the account (upsert with ignoreDuplicates), and local storage is cleared only after a successful merge. On sign-out, the account's favorites are copied back to local storage so they stay visible, tagged with the owner's user id so that a different account signing in on the same browser never inherits them. Auth state is resolved client-side (onAuthStateChange) to keep pages statically cacheable; the session cookie exchange happens in /auth/callback.
-
My Page & Review Flow (Sign-In Required) (/mypage): A personal hub whose only job is to answer “what should I review today, and why now?”. Account information is deliberately minimal (avatar, display name, sign-out); the screen is dominated by the review flow for favorite words. Signed-in users get a Leitner-style schedule (1 / 3 / 7 / 14 / 30-day intervals) stored in Supabase (word_review_progress, learning_streaks, both RLS-protected), so the same due queue and streak follow them across devices. The page shows today's due count with a progress ring, a 🔥 streak / best-streak / weekly-reviewed row, a four-segment retention breakdown (untouched / learning / familiar / mastered), the most-forgotten words, and links into the existing favorites, listen, study, and daily-picks screens. A filtered review snapshots at most 10 slugs when the session starts, removes each graded slug without refilling from the backlog, and ends on a completion screen. Authenticated sessions use queue- and user-scoped sessionStorage keys, and the answer’s “詳しい解説を見る” link carries the original queue so returning from the word detail keeps the same session context. Grading is optimistic, writes a user-scoped retry outbox to local storage before sending, serializes sends per user so rapid grades cannot finish out of order, and removes pending data only after Supabase accepts it; failed writes are merged and retried on the next review mount or grade. Next-due dates are snapped to the start of a later JST day so a nightly learner does not drift by a day. Favorites are read strictly from Supabase for authenticated review flows: /mypage and signed-in review sessions wait for favoritesStatus === "ready"; a signed-in favorites read failure shows a retry state instead of exposing a possibly stale local snapshot. Guests hitting /mypage, /review, or /favorites/listen get a login gate whose sign-in flow always returns to /mypage, with links to everything that stays free; only a signed-in progress-fetch error still degrades /review?queue=due|weak to the full favorites list with a notice. /review session storage keys are therefore always user- and epoch-scoped. All scheduling rules are pure functions in src/lib/review-schedule.ts (unit-tested), with Supabase access isolated in src/lib/review-progress-repo.ts and src/hooks/useReviewProgress.ts. Auth stays client-side (the proxy matcher is unchanged) so the page shell remains statically prerendered.
-
Single-Grade Review Detail Flow: Review Mode uses the same reveal-then-grade card as Study Mode, so each word is graded exactly once on the card and grading never leaves the session. Opening “詳しい解説を見る” before grading keeps the card ungraded; the detail-page return action “復習に戻る” brings the learner back to that same revealed card. Detail pages opened from Review Mode (from=review, with any queue or none) hide the previous/next word links, so learners cannot preview cards still waiting to be graded in the same session.
-
Analytics Events: GA4 tracks settled word-explorer queries with the recommended search event (700 ms debounce, 2+ characters, duplicate suppression), semantic searches (semantic_search with query length and result count; the query text is not sent), level/letter/search-mode filters (words_filter), and detail opens (word_detail_open, with source: semantic_search for meaning-search results) in addition to existing favorite/share events. My Page adds mypage_view (due count, favorite count, streak), mypage_login_gate_view (login-gate exposure for guests), and mypage_cta_click (which review/learning entry point was taken). The favorites review/listen gate adds favorite_practice_gate_view and favorite_practice_gate_cta, both carrying feature (review / listen / card).
-
Social Share: Share word details via Twitter, Facebook, and LINE (react-share), with GA4 event tracking.
-
PWA Ready: Installable on mobile and desktop via manifest.ts.
-
Dynamic OGP: Per-word Open Graph images generated on-the-fly via src/app/words/[word]/opengraph-image.tsx.
-
CDN-Cached OG Images (Active CPU control): Under cacheComponents: true, metadata image routes are never prerendered — even a route with no data access stays dynamic (ƒ), export const revalidate is inert, and generateStaticParams does not help; the build's prerender-manifest.json lists zero OG routes. The word OG route therefore carries no generateStaticParams / dynamicParams = false: keeping them only doubled the build's static-generation set (1,422 → 2,798 pages) with per-word prerender attempts that emit nothing, measurably degrading local builds (static generation 9.1s → 28.2s, whole build 17s → 35s, macOS compressed memory 4.7 GB → 11.4 GB, swapins 14k → 201k). Unknown slugs are rejected inside the Function by the getWordBySlug check, which returns a bare 404 with OG_IMAGE_NOT_FOUND_CACHE_CONTROL instead of rasterizing a "Not Found" image. Since each image costs a Satori layout pass plus a resvg 1200×630 PNG rasterization, leaving this unaddressed burns Vercel Fluid Active CPU in proportion to request volume. Both OG routes therefore send OG_IMAGE_CACHE_CONTROL (src/lib/og-utils.ts), letting the CDN hold the PNG so the Function runs roughly once per edge instead of once per request. s-maxage is 30 days to match the word-detail cache (WORD_CACHE_TTL_DAYS, cacheLife("max")), with stale-while-revalidate covering expiry. loadGoogleFont is wrapped in 'use cache' and fetches one stable full-TTF URL shared by every OGP. It deliberately omits Google Fonts' text= parameter: that parameter produced a different cache key per word while returning the same roughly 7 MB font, duplicating identical data across 1,300+ entries and exhausting build memory.
-
Outbound Timeouts & Selective Retries: External-call policy is centralized in src/lib/http-retry.ts, and every server/CLI outbound path has a timeout. fetchWithRetry keeps response decoding (json / text / arrayBuffer) inside the retry boundary and retries only statuses a resend can fix (408/425/500/502/503/504); 429 is deliberately excluded because Gemini and Google Cloud TTS are metered. Gemini SDK retries are disabled because SDK 1.50.x includes 429 and erases the final HTTP status; calls instead use retryWithTimeout, preserving ApiError.status and a fresh signal per attempt. Redis keeps one SDK network retry plus a short command timeout but does not replay ambiguous HTTP failures such as INCR. Upstash Vector uses a custom public requester so idempotent query/upsert/delete calls can retry selected HTTP 5xx while retaining their status. Vercel Blob list() is bounded separately with an AbortController. Route Handlers structurally classify SDK status / statusCode errors (429 → 429, 5xx → 502, timeout/abort → 504).
-
Lean Proxy Matching: src/proxy.ts refreshes the Supabase Auth session, with the matcher minimized to /login and /auth/* to keep Vercel Middleware/Proxy execution usage low (auth state elsewhere is handled client-side).
-
Static Pages: Includes About, Privacy, Terms, and Contact pages for better user trust and SEO. The Privacy Policy explicitly discloses Google AdSense / third-party ad vendors' Cookie usage and Google Analytics tracking, with opt-out links, in line with AdSense program policy requirements.
-
Learning Guide Articles (/guide): 16 article records, of which 15 are currently published. The May 2026 public-test retrospective is retained for source review but excluded from the guide index, static params, sitemap, related links, and search indexing. Published guides use visible Rain bylines, optional linked references, and Article + BreadcrumbList JSON-LD; unsupported score guarantees, fixed forgetting percentages, and unverifiable frequency claims have been removed or qualified. The index lists articles newest-first.
-
Cookie Consent: First-visit consent banner aligned with GA4 tracking. Consent is stored in a cookie and read server-side via CookieConsentGate; GoogleAnalyticsGate loads GA4 only after explicit acceptance. Both gates are wrapped in <Suspense> so the rest of the root layout remains cacheable.
-
AdSense Preparation: Ownership meta tag and ads.txt are retained; Google ad scripts are disabled. Affiliate banners are independently opt-in via NEXT_PUBLIC_AFFILIATE_ADS_ENABLED=true. Search indexing does not depend on advertising. Draft guides return not-found. Fifteen guides include revised explanations and nine original exercises. Editorial word corrections take precedence over Redis and generation; review hashes distinguish AI checks from human approval. See reapplication plan and review procedure.
-
Responsive Design: Optimized for desktop and mobile devices. Below 640px, word-detail audio/favorite buttons and home/favorites pagination have at least 44×44px tap targets; icon sizes and desktop sizing stay compact. (Updated: 2026-09-23)
-
Stronger Page Backgrounds: The TOP, word index, sign-in, favorites, daily picks, listening, study, and review screens share a more visible blue radial background, while word-detail pages retain their distinct teal hue with increased saturation.
Claude Code asks for approval before starting project-scoped MCP servers for the first time. Never commit credential values to .mcp.json or another tracked file.
Clears L1 (Next.js Data Cache) for a specific word. To also clear L2 (Upstash Redis) cache, add the upstash=true parameter. This forces a fresh AI generation on the next request if both caches are cleared.
Generates audio for words or sentences.
Finds vocabulary words by meaning (Japanese or English queries) via embedding similarity.
表示順は、ヒーロー → 今日のおすすめ単語 → 意味で探す（AI） → レベル別単語一覧（つづり検索）→ 全単語一覧 → はじめての方へ → 学習ガイド最新記事 → このサイトについて（できること・おすすめルーティン・運営者メッセージ）→ FAQ → 解説記事 → SNSシェアです。2つの検索は見出しと入力欄の文言で「意味で探す」「つづりで探す」と役割を分けています。初回学習の案内のボタンは、モバイルで高さ44px以上のタップ領域を確保しています。
