Spa Orchestrator

Single-Page Application (SPA) Orchestrator (2026 Edition)

English | Bahasa Indonesia

English

Orchestration & Integration

Connects and orchestrates with relevant domain skills like modern-web-guidance, brainstorming, zero-to-prod-orchestrator, and project-context-mapper to ensure cohesive execution.

• MANDATORY: Execute modern-web-guidance FIRST for all HTML/CSS and client-side JS tasks to ensure modern web standards.

Description

Structured orchestration guide for building modern Single-Page Applications (SPAs). Coordinates frontend architecture (TanStack Router, React 19, TanStack Query v5) with decoupled API backends (Hono RPC, tRPC). Covers state management strategy, routing patterns, API layer design, build tooling (Vite + TanStack Start), and deployment strategies.

Trigger Conditions

• Building a highly interactive dashboard, admin panel, or data-heavy web application as a SPA.
• Choosing between SPA vs SSR vs MPA for a new project.
• Setting up client-side routing with TanStack Router (type-safe routes, loaders).
• Structuring state management: server state (TanStack Query) vs client state (Zustand/Jotai).
• Building a decoupled frontend that communicates with a separate backend via Hono RPC or tRPC.
• Deploying a SPA to Cloudflare Pages, Vercel, or a CDN.

SPA vs SSR vs MPA — Decision Guide

Choose SPA when:
✅ Highly interactive app (dashboard, editor, admin panel)
✅ Rich client-side state that persists across navigation
✅ Auth-gated app (SEO is not a primary concern)
✅ Already have a separate backend API

Choose SSR (Next.js) when:
✅ SEO is critical (marketing pages, public content)
✅ Fast initial page load for unauthenticated users
✅ Mixed app: some public pages + some gated app pages

Choose MPA (Astro, Django, Laravel) when:
✅ Mostly static content, minimal interactivity
✅ SEO is the primary concern
✅ Small team that wants to avoid JS complexity
  → see mpa-orchestrator skill

Recommended SPA Stack (2026)

TanStack Router — File-Based Type-Safe Routing

src/routes/
  __root.tsx          # Root layout (providers, nav)
  index.tsx           # / — landing/home
  _auth.tsx           # Auth guard layout
  _auth/
    dashboard.tsx     # /dashboard (auth required)
    settings/
      index.tsx       # /settings
      profile.tsx     # /settings/profile
  _public.tsx         # Public layout
  _public/
    login.tsx         # /login

// src/routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router';
import type { QueryClient } from '@tanstack/react-query';

interface RouterContext {
  queryClient: QueryClient;
  auth: { user: User | null; isAuthenticated: boolean };
}

export const Route = createRootRouteWithContext<RouterContext>()({
  component: () => (
    <div>
      <Navbar />
      <Outlet />
    </div>
  ),
});

// src/routes/_auth/dashboard.tsx — protected route with data preloading
import { createFileRoute, redirect } from '@tanstack/react-router';
import { workspacesQueryOptions } from '@/queries/workspaces';

export const Route = createFileRoute('/_auth/dashboard')({
  // Runs before render — redirect if not authenticated
  beforeLoad: ({ context }) => {
    if (!context.auth.isAuthenticated) {
      throw redirect({ to: '/login' });
    }
  },
  // Prefetch data in loader — no loading state on initial render
  loader: ({ context: { queryClient } }) =>
    queryClient.ensureQueryData(workspacesQueryOptions()),
  component: DashboardPage,
});

function DashboardPage() {
  // Data is already available — no loading state
  const { data: workspaces } = useSuspenseQuery(workspacesQueryOptions());
  return <WorkspaceList workspaces={workspaces} />;
}

State Management Architecture

State Layers:
┌─────────────────────────────────────┐
│  Server State (TanStack Query v5)   │  ← API data, cached, auto-refetch
│  workspaces, users, projects, etc.  │
├─────────────────────────────────────┤
│  Client State (Zustand)             │  ← UI state, sidebar open, theme
│  modals, filters, UI preferences    │
├─────────────────────────────────────┤
│  Form State (React Hook Form)       │  ← Active form inputs, validation
│  Scoped to individual forms         │
├─────────────────────────────────────┤
│  URL State (TanStack Router)        │  ← Shareable page state
│  search params, active tab, page #  │
└─────────────────────────────────────┘

// URL State — persist filter state in URL (shareable)
import { createFileRoute, useNavigate } from '@tanstack/react-router';
import { z } from 'zod';

const searchSchema = z.object({
  page: z.number().int().positive().default(1).catch(1),
  search: z.string().default('').catch(''),
  status: z.enum(['all', 'active', 'archived']).default('all').catch('all'),
});

export const Route = createFileRoute('/_auth/projects')({
  validateSearch: searchSchema,
  component: ProjectsPage,
});

function ProjectsPage() {
  const { page, search, status } = Route.useSearch();
  const navigate = useNavigate({ from: Route.fullPath });

  const setSearch = (q: string) =>
    navigate({ search: (prev) => ({ ...prev, search: q, page: 1 }) });

  return (
    <div>
      <SearchInput value={search} />
      <ProjectList page={page} search={search} status={status} />
    </div>
  );
}

Hono RPC — Decoupled Type-Safe API

// apps/api/src/index.ts — backend Hono app
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';

const workspacesRoute = new Hono()
  .get('/', async (c) => {
    const user = c.get('user');
    const workspaces = await db.workspace.findMany({
      where: { members: { some: { userId: user.id } } },
    });
    return c.json(workspaces);
  })
  .post('/', zValidator('json', CreateWorkspaceSchema), async (c) => {
    const data = c.req.valid('json');
    const workspace = await db.workspace.create({ data });
    return c.json(workspace, 201);
  });

const app = new Hono()
  .use('*', authMiddleware)
  .route('/workspaces', workspacesRoute);

export type AppType = typeof app;
export default app;

// apps/web/src/lib/api.ts — type-safe client
import { hc } from 'hono/client';
import type { AppType } from '@myapp/api';

export const api = hc<AppType>(import.meta.env.VITE_API_URL);

// TanStack Query integration
export const workspacesQueryOptions = () =>
  queryOptions({
    queryKey: ['workspaces'],
    queryFn: async () => {
      const res = await api.workspaces.$get();
      return res.json(); // Fully typed!
    },
    staleTime: 5 * 60 * 1000,
  });

Build & Deployment

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { TanStackRouterVite } from '@tanstack/router-plugin/vite';

export default defineConfig({
  plugins: [
    TanStackRouterVite(), // Auto-generates route tree
    react(),
  ],
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom'],
          'vendor-query': ['@tanstack/react-query'],
          'vendor-router': ['@tanstack/react-router'],
        },
      },
    },
  },
});

Deployment target: Cloudflare Pages or Vercel for CDN-served static SPA. Backend API deployed separately to Railway/Fly.io.

Bahasa Indonesia

Integrasi Orkestrasi

Terhubung dan mengorkestrasi skill domain yang relevan seperti modern-web-guidance, brainstorming, zero-to-prod-orchestrator, dan project-context-mapper untuk memastikan eksekusi yang kohesif.

• MANDATORY: Eksekusi modern-web-guidance PERTAMA KALI untuk semua tugas HTML/CSS dan JS sisi klien guna memastikan standar web modern.

Deskripsi

Panduan orkestrasi terstruktur untuk membangun Single-Page Application (SPA) modern. Mengkoordinasikan arsitektur frontend (TanStack Router, React 19, TanStack Query v5) dengan backend API terpisah (Hono RPC, tRPC). Mencakup strategi state management, pola routing, desain API layer, build tooling (Vite + TanStack Start), dan strategi deployment.

Kondisi Pemicu

• Membangun dashboard yang sangat interaktif, panel admin, atau aplikasi web berat data sebagai SPA.
• Memilih antara SPA vs SSR vs MPA untuk proyek baru.
• Menyiapkan client-side routing dengan TanStack Router (rute type-safe, loader).
• Menyusun state management: server state (TanStack Query) vs client state (Zustand/Jotai).
• Membangun frontend terpisah yang berkomunikasi dengan backend terpisah via Hono RPC atau tRPC.
• Men-deploy SPA ke Cloudflare Pages, Vercel, atau CDN.

SPA vs SSR vs MPA — Panduan Keputusan

Pilih SPA saat: aplikasi sangat interaktif (dashboard, editor, panel admin), state sisi klien yang kaya, aplikasi yang dibatasi auth (SEO bukan perhatian utama).

Pilih SSR (Next.js) saat: SEO sangat penting, load halaman awal yang cepat untuk pengguna yang tidak terautentikasi, aplikasi campuran.

Pilih MPA (Astro, Django, Laravel) saat: konten sebagian besar statis, SEO adalah perhatian utama — lihat skill mpa-orchestrator.

Stack SPA yang Direkomendasikan (2026)

Vite 6 untuk build, TanStack Router untuk routing type-safe, TanStack Query v5 untuk server state, Zustand untuk client state, Hono RPC untuk API layer type-safe, React Hook Form + Zod untuk form, Tailwind CSS v4 untuk styling, dan GSAP untuk animasi kompleks.

TanStack Router — Routing File-Based Type-Safe

Atur rute dalam direktori src/routes/ dengan layout bersarang. Gunakan createFileRoute dengan beforeLoad untuk guard autentikasi, loader untuk prefetch data, dan validateSearch untuk URL state yang dapat dibagikan.

Arsitektur State Management

Empat lapisan state yang saling melengkapi: Server State (TanStack Query), Client State (Zustand), Form State (React Hook Form), dan URL State (TanStack Router search params).

Hono RPC — API Type-Safe Terpisah

Ekspor AppType dari backend Hono dan gunakan hc<AppType>() di frontend untuk panggilan API yang fully typed tanpa codegen.

Build & Deployment

Gunakan plugin TanStackRouterVite untuk auto-generate route tree. Konfigurasi manualChunks untuk code splitting yang optimal. Deploy SPA ke Cloudflare Pages atau Vercel; backend API ke Railway/Fly.io secara terpisah.

📄 Standard Pages Mandate (CRITICAL)

MANDATORY: Whenever you are building a new application, landing page, or website, you MUST automatically create the following standard pages:

1. About Page (/about)
2. Profile Page (/profile)
3. Contact Page (/contact)
4. Terms of Reference / Terms of Service (/terms)
5. Privacy Policy (/privacy-policy)

These pages must be generated with standard boilerplate content that can later be customized to fit the specific application. Do not wait for the user to ask for them; they are a strict requirement for all web projects. / WAJIB: Otomatis buatkan halaman standar (About, Profile, Contact, Terms, Privacy Policy) pada setiap pembuatan aplikasi/website baru dengan konten boilerplate yang bisa disesuaikan nanti.