Capstone: A Production SPA

The capstone is where the roadmap stops being fifteen separate topics and becomes one application. The first decision is where each piece you have learned lives in the codebase — because a production SPA falls apart not from a missing feature but from a structure nobody can navigate six months later.

A layout that scales from a weekend build to a team:

src/
├── api/
│   ├── client.ts            # fetch wrapper: baseURL, auth header, error normalization
│   ├── orders.ts            # typed endpoint functions, one per resource
│   └── types.ts             # shared response contracts
├── components/              # presentational, props in / events out
├── composables/             # useCart, usePolling, useMediaQuery
├── layouts/                 # AppLayout, AuthLayout
├── router/
│   ├── index.ts             # route table, lazy imports
│   └── guards.ts            # auth redirect logic
├── stores/                  # Pinia slices: auth, cart, ui
└── views/                   # routed pages, one per route

Three rules make this structure pay for itself. Views compose, components stay dumb — a view reads stores and calls the API layer; a component receives props and emits events, so both test in isolation with the mounting patterns from Mounting Components in Tests. All HTTP goes through src/api/ — no component calls fetch directly, which puts exactly one file in mocking scope for every test:

// src/api/client.ts
const BASE = import.meta.env.VITE_API_URL

export async function api<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    headers: {
      'content-type': 'application/json',
      ...(auth.token ? { authorization: `Bearer ${auth.token}` } : {}),
      ...init?.headers,
    },
  })
  if (!res.ok) throw new ApiError(res.status, await res.text())
  return res.json() as Promise<T>
}

Routes are lazy by default — every entry in the router uses () => import('@/views/CheckoutView.vue') so the initial chunk stays small, the discipline from Async Components and Code Splitting applied as a house rule rather than a per-feature decision:

// src/router/index.ts
const routes = [
  { path: '/', component: () => import('@/views/HomeView.vue') },
  { path: '/login', component: () => import('@/views/LoginView.vue'), meta: { public: true } },
  { path: '/orders/:id', component: () => import('@/views/OrderView.vue'), meta: { auth: true } },
]

Metadata on the route records (public, auth, guestOnly) is what the guard in the next chapter reads — putting the claim on the route itself keeps guard code declarative. Layouts wrap routed views through <RouterView> slots so header, navigation, and error boundary are declared once instead of copied into every view.

How the roadmap's topics land in this tree is worth seeing as one table — it is the answer to "what was all that for?":

Settings come from environment variables — VITE_API_URL at build time — never hard-coded, and never secrets: anything prefixed VITE_ is public in the bundle, a constraint covered in Environment Variables in Vite.

Before writing features, pin the skeleton down: route table, one store, the API client, one view per column of that table, and a smoke test per view. The structure reviewed once now is what keeps every feature PR after it small.

Two flows decide whether the capstone feels like a real product: an unauthenticated visitor must be bounced to login and returned to where they were, and an expired token must refresh once — not five times when five requests fail together. Both are worth building deliberately, then proving with tests.

The guard lives in router/guards.ts and runs before every navigation:

router.beforeEach((to) => {
  const auth = useAuthStore()

  if (to.meta.public) return true
  if (!auth.token) {
    return { path: '/login', query: { redirect: to.fullPath } }   // remember the destination
  }
  if (to.meta.guestOnly && auth.token) return { path: '/' }
  return true
})

Two details make this production-grade: redirect: to.fullPath preserves query and hash so the user lands back on /orders/42?tab=invoice, and meta flags on the route records keep guard logic declarative instead of a growing path blacklist. The store reads token state from Pinia, which the guard creates through useAuthStore() outside the component tree — Pinia supports this once setActivePinia is configured, and it is the same outside-a-component pattern composables rely on.

Token refresh is where most implementations go wrong. Five parallel requests hit 401 at the same moment; a naive interceptor refreshes on each, and the refresh endpoint rotates the token — four of those calls invalidate the whole session. The fix is a single shared refresh promise: the first 401 starts the refresh, everyone else awaits that same promise.

let refreshing: Promise<string> | null = null

export async function request(path: string, init?: RequestInit) {
  const first = await api(path, init)
  if (first.status !== 401) return first.json()

  refreshing ??= refreshAccessToken()          // only the first caller refreshes
  try {
    const token = await refreshing
    return (await retryWith(token)).json()     // others join this line
  } finally {
    refreshing = null                          // ready for the next real expiry
  }
}

??= is the whole trick: concurrent failures collapse into one refresh, each caller retries with the new token, and the flag clears in finally whether the refresh succeeded or not.

Now the tests, which is where this topic reunites with the testing phase. The suite mocks the API module at its boundary and mounts the app with the real router:

vi.mock('@/api/client', () => ({ api: vi.fn() }))
import { api } from '@/api/client'

test('redirects an unauthenticated visitor and returns them after login', async () => {
  const router = createRouter({ /* real route table */ })
  const wrapper = mount(RouterViewHost, { global: { plugins: [router, pinia] } })

  await router.push('/orders/42')
  await flushPromises()

  expect(wrapper.find('h1').text()).toBe('Sign in')
  expect(router.currentRoute.value.query.redirect).toBe('/orders/42')
})

test('two parallel 401s trigger exactly one refresh', async () => {
  const refresh = vi.mocked(refreshAccessToken)
  await Promise.all([request('/a'), request('/b')])
  expect(refresh).toHaveBeenCalledTimes(1)
})

The critical-flows list the capstone must cover before deploy: login success and failure, the guarded redirect round-trip, add-to-cart from a product page, checkout validation blocking an empty address, logout clearing the store. Stub the heavy children, mock @/api/client, use fake timers for any debounce — the isolation toolkit from Mocking Modules and Stubbing Children applies unchanged. What the tests must not do is mock the router or the store: those are the wiring under test, and Testing Composables in Isolation drew that same line — mock the boundary, run the code you are claiming about.

Add the failure branch of refresh while you are here, because it is where sessions actually die: if the refresh request itself returns 401, clear the token, drop the queued retries, and navigate to login — a user stuck on a page that silently 401s forever is worse than one who is asked to sign in again. The test asserts exactly that: request('/a') rejects after a failed refresh, auth.token is null, and the store's logout spy ran once. Three tests — redirect round-trip, single-flight refresh, failed-refresh logout — now pin the entire auth behavior, and any refactor of guards.ts or the interceptor that breaks a session has to go green against them first.

With auth proven green, the last chapter measures what it all costs to ship.

A capstone that works on your laptop but ships a 900 KB bundle or fails Lighthouse under 70 is not finished. The finishing line is measurable: a budget written down, checked in CI, failing the build when it is exceeded. Numbers first, opinions later.

Run the real build and read the output:

npm run build          # vite build — note the largest chunks
npx vite-bundle-visualizer   # which imports dominate the graph
npm run preview        # production server locally; verify routing rewrites

A realistic first measurement for a routed SPA: index chunk around 70 KB gzip (Vue + router), a 90 KB vendor chunk, and feature chunks of 15–40 KB each. If checkout alone ships 200 KB, something heavy — a date library, a chart kit — entered through a barrel import, and the fix is the chunk strategy you already know: split vendor groups with manualChunks and lazy-load the route that needs them.

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router', 'pinia'],   // changes rarely → long cache
        },
      },
    },
  },
})

Grouping the framework separately means a product release re-uploads only your code's chunks while visitors keep the cached vendor file — the cache-hit half of the deployment story.

Write the budget as a table, and put the same table in CI:

Lighthouse CI enforces this mechanically rather than by memory:

{
  "ci": {
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "total-byte-weight": ["error", { "maxNumericValue": 512000 }]
      }
    }
  }
}

The pipeline order matters — fail fast on the cheap checks: lint → unit tests (vitest run) → build → bundle budget → Lighthouse against the preview server → deploy. A green unit suite is the gate; Lighthouse runs on the built output because source-level performance tells you nothing about what users download.

Deployment closes the loop with routing, and it is where the SPA rewrite rule earns its keep: unknown paths fall back to index.html so the history router can resolve /orders/42, real files and /api/* are excluded from the rewrite, hashed assets get cache-control: immutable, and index.html gets no-cache. Every point of that checklist is detailed in Deploying a Single-Page App — the capstone's job is to prove your host's config actually implements it, which you verify with a direct request to a deep link:

curl -I https://app.example.com/orders/42   # must return 200 with the index document
curl -I https://app.example.com/assets/index-a1b2c3.js   # must return immutable caching

Then walk the release like a user on a throttled connection: cold load, deep-link refresh, login redirect round-trip, offline error state. Anything that only worked on npm run dev surfaces here — and the four checks that catch regressions later are the same four the capstone has used all along: route rewrites respond, the bundle stays inside its budget, the guarded flows pass their tests, and Lighthouse holds its score. Ship it, then keep that pipeline running on every commit — the capstone is not a demo you present once; it is the project whose tests, budgets, and deploy checks you can defend line by line in the interview that follows.