DongHyeonka 9e20d471b0 fix(build): 부팅 실패 화면이 앱 그래프 청크 없이 그려진다
앱 모듈 하나가 평가 중에 예외를 던지면 main.tsx는 부팅 실패 화면
(render-boot-failure.tsx)을 그린다. 그런데 그 청크가 route-not-found
청크에서 값 둘을 import하고, route-not-found에는 React, i18n 카탈로그,
installed-feature-messages.ts가 같이 들어 있다. 그래서 예외를 던진
청크에 실패 화면도 같이 걸려 그리지 못하고, 정적 「불러오는 중」
화면이 계속 남는다(boot-module-failure e2e, 세 엔진 모두).

원인은 vite.config.ts의 manualChunks다. Rolldown은 manualChunks를
includeDependenciesRecursively가 기본값(true)인 group으로 바꾼다. 그래서
route-not-found로 지정한 Public not-found 화면이 자기 정적 의존을 전부
그 청크로 끌고 간다. PR #6 전(27e342d) 빌드도 같은 import가 있었다.

템플릿과 같은 output.codeSplitting.groups 형식으로 바꾼다. react-dom과
route 화면 group은 includeDependenciesRecursively: false로 둬서, 화면
모듈만 그 이름의 청크에 들어가게 한다. 공유 모듈은 Rolldown이 쓰는
쪽에 따라 나눈다. preload-helper·react-dom·route 청크 이름은 그대로다.

검증:
- build-environment-bundle.test.ts에 시험 하나를 더했다. 실패 화면
  청크에서 정적 import로 닿는 청크 가운데 installed-feature-messages의
  오류 문구가 든 것이 없어야 한다. 고치기 전에는
  route-not-found-*.js가 잡혀 실패했고, 고친 뒤 통과한다.
- vite-route-chunks, bundle-*, chunk-recovery*, performance-budgets 단위
  시험(29건) 통과.
- e2e: boot-module-failure, old-tab-chunk-recovery,
  service-worker-update·recovery, production-csp가 chromium·firefox·
  webkit에서 통과한다.
2026-11-12 18:38:30 +09:00

Tech Log Frontend

Initialized from clean-architecture-frontend-template revision 4dc033cf33a5b6173bbf960d5eb464a406dc4c92. The exact source identity is recorded in template.lock.json.

A React/Vite TechLog application where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.

Start locally

Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and Corepack. The repository pins pnpm in package.json.

Product source, tests, build/quality scripts, and supported tool configuration are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly on the pinned Node 24 runtime and are checked with NodeNext resolution plus erasable-syntax enforcement. Project-owned executable source contains no JavaScript-family files; negative architecture, security, and type-compatibility fixtures are TypeScript/TSX as well.

corepack pnpm install --frozen-lockfile
corepack pnpm dev

Runtime configuration

Runtime-public settings are validated against one schema before the product tree mounts (runtimeConfigV2ArtifactSchema in src/contracts/release-artifacts.ts). Client secrets are forbidden.

The source of truth is config/runtime/<profile>.json, one file per environment: local, development, staging, production. corepack pnpm build writes dist/config.json from the selected profile (scripts/generate-runtime-config.ts). public/config.json is only the local profile for corepack pnpm dev; the build replaces it, so settings put there never reach a deployment. Keep it equal to config/runtime/local.json plus BUILD_ID: local-build and RELEASE_ID: local-release; tests/unit/deployment-admission.test.ts fails when the two differ.

Build and deploy variables, lowest precedence first:

Variable Sets Default
APP_PROFILE which config/runtime/<profile>.json is used local; an empty value fails the build
RUNTIME_API_BASE_URL API_BASE_URL, overriding the profile the profile value
RUNTIME_TELEMETRY_ENDPOINT TELEMETRY_ENDPOINT, overriding the profile the profile value
VITE_BUILD_ID BUILD_ID in the runtime config and the release manifest local-build
RELEASE_ID RELEASE_ID in the runtime config and the release manifest local-release
RELEASE_TARGET the environment FE-GATE-027 admits the build to; must equal APP_PROFILE none; admission refuses without it

verify:documentation fails if this table stops naming a variable the build or admission reads (scripts/verify-documentation-readiness.ts).

Only the two RUNTIME_* values can differ from the reviewed profile. Anything else changes by editing the profile file. Staging and production reject demo auth and non-HTTPS endpoints.

A production build and its admission check:

APP_PROFILE=production \
RUNTIME_API_BASE_URL=https://api.example.com/ \
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission

With CI=true the gate runner (corepack pnpm ci:gate) also requires VITE_COMMIT_SHA, SOURCE_DATE_EPOCH and CI_RUNNER_IMAGE before it runs a gate (scripts/lib/build-environment.ts, scripts/run-ci-gate.ts). The CI variable list is in docs/operations/ci-quality-gates.md.

TechLog experience

The default build mounts the source-faithful TechLog Public and Studio experience. Public routes provide discovery, search, documents, topics, projects, releases, and profile content. /studio provides the session-scoped mock authoring workflow: create, edit, validate, preview, publish, unpublish, and immutable publication history.

The 27 canonical route definitions are divided into PUBLIC and STUDIO nested layouts. Studio authentication remains deliberately deferred; its mock gateway state lasts for one Studio shell session and resets on a full document load. The exact route, dependency, stylesheet, asset, and parity inventory is recorded in docs/operations/techlog-ui-migration-baseline.md.

corepack pnpm build emits a self-contained dist/server.mjs production boundary. corepack pnpm preview --host 127.0.0.1 --port 4174 serves known Public and Studio routes as SPA documents, preserves the in-shell Studio 404, and returns source-exact raw 404 text/plain responses for missing Public content. With the read-only source temp-copy server on 4375, run:

TECH_LOG_SOURCE_URL=http://127.0.0.1:4375 \
TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \
corepack pnpm verify:tech-log-source-parity

Studio backend source

TECH_LOG_STUDIO_SOURCE (MOCK | HTTP) selects which StudioGateway adapter the composition root wires up. It defaults to MOCK — the session-scoped in-memory Studio described above — so the existing Studio workflow and its test suites are unaffected unless the switch is deliberately turned on. Setting it to HTTP wires the HTTP StudioGateway instead, which calls the canonical @tech-log/studio-contract operations against API_BASE_URL. With no backend reachable at that URL, Studio still boots and its shell renders; the specific panels that need the backend show an inline "failed to load" state rather than a blank screen or an unhandled exception.

The switch is a field on the versioned runtime config document (RuntimeConfigV2), not a build-time flag:

  • config/runtime/{local,development,staging,production}.json are the deployment profiles corepack pnpm build (via scripts/generate-runtime-config.ts) materializes into dist/config.json for a real build.
  • corepack pnpm dev does not run that step. Plain vite serves public/config.json (and public/release-manifest.json) verbatim as dev fixtures — editing config/runtime/local.json alone has no effect on pnpm dev. To exercise HTTP mode under pnpm dev, set TECH_LOG_STUDIO_SOURCE in public/config.json directly.

The dev release manifest must declare the compiled contract set

Contract-set verification runs unconditionally at boot, before any adapter is selected. It is not an HTTP-mode caveat: if public/release-manifest.json's contractSet does not match the set the build compiled, corepack pnpm dev does not start the app at all — it renders the fail-closed boot screen (CONTRACT_SET_MISMATCH / CONTRACT_SET_PACKAGE_MISSING) in the default MOCK mode too. A developer who runs pnpm dev and gets a boot error has a broken dev server, however tidy the screen looks; treat it as a defect in the fixture, never as expected behaviour.

The expectation comes from EXPECTED_CONTRACT_SET_PACKAGES (src/features/installed-contract-contributions.ts), and a real build writes it into dist/release-manifest.json from scripts/generate-contract-set.ts, so production builds are always self-consistent. Only the hand-maintained dev fixture can drift, and it drifts whenever either half moves — a regenerated contract (new package digest or version) or a contribution added to or removed from installed-contract-contributions.ts. Two things keep it honest:

  • corepack pnpm generate:tech-log-contract refreshes the fixture's contractSet block as its last step, so regenerating the contract can never leave the two out of step. corepack pnpm generate:dev-release-manifest refreshes the same block on its own, for the contribution-list case that does not go through contract generation.
  • corepack pnpm check:dev-release-manifest is the gate. It compares the fixture's setAlgorithm, setDigest and package set against the compiled set and fails on any difference. It runs in CI as part of FE-GATE-010, which is what catches the changes the generation step cannot see.

TechLog contract generation

The Studio HTTP contract is vendored from a canonical OpenAPI source, not hand-written:

  • corepack pnpm generate:tech-log-contract regenerates src/features/tech-log/contracts/studio/studio-api.openapi.yaml, generated.ts, and canonical-source.json from the canonical tech-log-design-package repository (path from TECH_LOG_DESIGN_PACKAGE, default /home/donghyeon/workspace/tech-log-design-package). It needs that repository checked out locally and network access, because type generation runs in an isolated pnpm dlx sandbox (this repo pins TypeScript 7, which has no classic compiler API for openapi-typescript to use). Run it after the canonical contract changes, then commit the regenerated files.
  • corepack pnpm check:tech-log-contract is the drift gate: it hashes the vendored yaml against the recorded digest and confirms every recorded operationId is present in both the yaml and the generated types. It needs neither the canonical repository nor the network, so it runs in CI and in this sandbox. Run it any time to confirm the vendored contract has not drifted from what was last generated.

Support scope

Four tiers. The status words on the right are the ones the catalogs and design documents use; the next table maps them.

Tier What it covers Status words
Default In the default build and covered by the merge gates: the TechLog Public and Studio shells and routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, AUTH_MODE=external (demo only in local/development), and the typed message catalog. dist/ is served by a static host (docs/architecture/static-delivery.md) COMPOSED
Optional (recipe) Not installed. A project copies one of the recipes in config/recipes/frontend-capability-recipes.json and narrows it (docs/architecture/optional-adapter-recipes.md). realtime, offline-indexeddb, service-worker-pwa and file-transfer also ship a tested reference runtime that the default build leaves out RECIPE_AVAILABLE, NOT_INSTALLED, AVAILABLE_NOT_COMPOSED
Experimental Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. src/features/local-draft-feature is an architecture sample, not installed; so is src/features/reference-feature, the template's removable sample, whose screens this product deleted DESIGNED_NOT_IMPLEMENTED
Not supported Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs NOT_SELECTED, PLATFORM_LIMITED

The rows come from docs/architecture/browser-data-capability-completion-ledger.md, docs/architecture/client-cache-and-storage.md and docs/architecture/api-contract-schema-mapper-and-server-state.md.

Status word Where it appears Meaning Tier
COMPOSED capability ledger, design documents wired into the default production path Default
INSTALLED a project's own recipe catalog (step 10 of the recipe procedure) the project added the recipe Default, for that project
RECIPE_AVAILABLE recipe catalog status a recipe exists to copy; nothing is installed Optional
NOT_INSTALLED recipe catalog defaultStatus; a src/features/<id>/NOT_INSTALLED marker file not part of the build Optional (recipe) or Experimental (feature)
AVAILABLE_NOT_COMPOSED capability ledger; recipe referenceRuntime.status code and tests exist; the default build leaves it out Optional
DESIGNED_NOT_IMPLEMENTED capability ledger, design documents design approved, runtime missing Experimental
NOT_SELECTED capability ledger, design documents deliberately not chosen Not supported
PLATFORM_LIMITED capability ledger browsers cannot guarantee it; offered only behind a probe and a fallback, if at all Not supported as a guarantee

Gate results (PASS, PASS_SCOPED, UNVERIFIED, FAIL_UNVERIFIED) are verdicts on evidence, not support tiers.

Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and iOS 16.4. That is the higher of Vite 8's default JavaScript target (baseline-widely-available; vite.config.ts sets no build.target) and the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright 1.62 pins, plus one Chromium phone-size smoke (playwright.config.ts). Older versions inside the target range and real mobile browsers are not tested.

Architecture

This repository is a Frontend Application Foundation: a starter/composition skeleton plus a reusable capability platform. Platform capabilities stay horizontal while product business features use vertical slices.

Dependencies point inward:

presentation -> application -> domain
adapters -----^
bootstrap composes concrete adapters
feature use case -> feature port <- feature-owned capability binding

See docs/architecture/frontend-application-foundation.md, docs/architecture/overview.md, docs/architecture/layers.md, and docs/architecture/starter-experience.md. TechLog is one feature boundary under src/features/tech-log. Its immutable Public catalog and session-scoped Studio mock gateway are injected through the application feature input; Public and Studio presentation code shares the typed content renderer without importing concrete adapters. The retained reference feature remains a non-product platform contract fixture and can be removed without changing the TechLog route set.

Platform capability review

The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:

These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.

Documentation

docs/README.md sorts the documents into current contracts, target designs and work history.

Files you can delete after copying

These record how the template and this product were built. Nothing in the build or the gates reads them, except the one file noted below (tests/unit/deletable-history-documents.test.ts checks this).

Path Contents
docs/superpowers/ past plans and specs
docs/reviews/ reviews. Keep docs/reviews/adapters/INVENTORY.md: check:adapter-inventory (FE-GATE-010) reads it

The template's own SPEC.md, tasks/ and CLAUDE.md were never carried into this repository (docs/operations/template-sync-2026-09-29.md).

The reference feature is not in this list: deleting its directory alone leaves tests, policy entries and CI scripts behind that fail the gates. scripts/test-sample-removal.ts removes it from a copy of the repository and lists everything that has to go with it (its header comment and SAMPLE_EXTRAS); do the same in your project and run the gates.

Verification

Common local checks:

corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci
corepack pnpm exec vitest run tests/features/tech-log
corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts tests/e2e/tech-log-studio-workflow.spec.ts tests/e2e/tech-log-responsive.spec.ts tests/e2e/tech-log-accessibility.spec.ts --project=chromium
corepack pnpm test:visual

drill:runbooks stops at the first drill that is not PASS. Without provider evidence every drill ends UNVERIFIED (exit 3), because a drill never reports a check it could not run locally as PASS; see "Runbook jobs" in docs/operations/ci-quality-gates.md.

test:all is the ordinary product-development loop and intentionally excludes host-level CI-runner assurance. Run corepack pnpm test:system only on the compatible Linux assurance host described in docs/testing/taxonomy.md.

check:types는 source, Node scripts/config와 tests를 분리된 TypeScript project로 모두 검사한다. type/architecture/security/registry의 invalid fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로 실행된다. 도구 호환성 결정은 VD-01에 기록돼 있다.

Application feature input은 module augmentation으로 닫힌 ID와 정확한 input shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의 failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는 TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고 runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import, parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용 TypeScript/TSX negative fixture로도 검증된다.

Install the pinned Playwright browser engines before the first cross-browser run:

corepack pnpm exec playwright install --with-deps chromium firefox webkit

Two gates intentionally need external evidence:

  • review:a11y-manual (release gate FE-GATE-028) needs a signed human keyboard/focus/screen-reader review for all 27 registered routes: NOT_FOUND, TECH_LOG_CASE, TECH_LOG_EXPLORE, TECH_LOG_EXPLORE_KIND, TECH_LOG_HOME, TECH_LOG_PROFILE, TECH_LOG_PROJECT, TECH_LOG_PROJECTS, TECH_LOG_PROJECT_ACTIVITY, TECH_LOG_PROJECT_DECISIONS, TECH_LOG_PROJECT_RECORDS, TECH_LOG_QUESTION, TECH_LOG_REFERENCE, TECH_LOG_RELEASE, TECH_LOG_RELEASES, TECH_LOG_SEARCH, TECH_LOG_STUDIO_DOCUMENTS, TECH_LOG_STUDIO_DOCUMENT_EDIT, TECH_LOG_STUDIO_DOCUMENT_NEW, TECH_LOG_STUDIO_DOCUMENT_PREVIEW, TECH_LOG_STUDIO_DOCUMENT_PUBLISH, TECH_LOG_STUDIO_DOCUMENT_VALIDATION, TECH_LOG_STUDIO_HOME, TECH_LOG_STUDIO_NOT_FOUND, TECH_LOG_STUDIO_PUBLICATIONS, TECH_LOG_STUDIO_PUBLICATION_PREVIEW, TECH_LOG_TOPIC. verify:documentation derives that list from the route registry and fails if this paragraph falls behind it. The merge gate FE-GATE-009 runs only review:a11y-manual -- --format-only, which checks that every route record keeps the template's fields, reviewed or still pending.
  • collect:web-vitals-evidence stays FAIL_UNVERIFIED until a reviewed minimum eligible-sample threshold and 28 days of production data exist.

Live hosting verification (FE-GATE-019, production stage) requires HOSTING_BASE_URL and a deployed promoted release; without it the result is UNVERIFIED, not PASS.

CI and evidence

The gate registry is config/ci/gates.json; the Gitea workflow is .gitea/workflows/quality-gates.yml. It follows:

MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY

DOCUMENTATION_READY is independent. No gate is downgraded to a warning.

The workflow runs on pull requests, pushes to main, and v* tags. The Git host of this repository may not have Actions enabled, so a pull request can show no gate status at all; no status is not a pass. Until the host runs the workflow and marks the merge gates as required checks, run the 13 merge gates locally before merging (FE-GATE-008 and 009 need Playwright browsers):

for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
  corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done

Machine-readable evidence is written below artifacts/; generated evidence is ignored by Git while .gitkeep files preserve the taxonomy.

Operational details are in docs/operations/, with incident procedures in docs/runbooks/.

Updating a copied project

Template versions are Git tags vX.Y.Z. The template repository's CHANGELOG.md lists the changes between tags, marks security fixes [보안] and contract changes [계약] (backend, deployment, CI or feature code must change too), and names the affected paths.

Record where you started. The template suggests a one-line .template-origin file; this repository records the same thing, more precisely, in template.lock.json (sourceRevision and sourceTree), and every sync is written up in docs/operations/template-sync-*.md.

Take a template fix with Git. cherry-pick works even when your repository does not share the template's history, because it merges against the picked commit's parent:

git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main   # what changed since you copied
git cherry-pick -x <commit>                      # one fix; -x records its origin

When the files have moved or diverged too far for a clean pick, read the change as a diff and apply it by hand:

git diff <commit>^ <commit> -- <paths from CHANGELOG>

Afterwards run the local merge gates from "CI and evidence", apply the backend or deployment change a [계약] row names, and update template.lock.json once you have caught up to a tag. git revert undoes a pick.

Defects: if a problem reproduces on an unmodified checkout of the template at template.lock.json's sourceRevision, it is a template defect. Report it on the template repository with that commit and the reproduction; the template maintainer classifies it and ships the fix with a CHANGELOG entry. A problem that needs your changes to reproduce belongs to your project, and applying a template fix to your copy is your project's job.

S
Description
No description provided
Readme
47 MiB
Languages
TypeScript 96.9%
CSS 3%