Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

3.6 KiB

Raw Blame History

Correct Nesting Order: RouterView, Transition, KeepAlive, Suspense

Rule

When combining <Suspense> with <Transition>, <KeepAlive>, and <RouterView>, the nesting order must be: RouterView -> Transition -> KeepAlive -> Suspense. Incorrect nesting causes components to not work together properly.

Why This Matters

Each of these components wraps and controls its child in specific ways. Incorrect nesting leads to:

Transitions not animating
Components not being cached by KeepAlive
Suspense not catching async dependencies
Subtle bugs that are hard to diagnose

Bad Code

<template>
  <!-- Wrong order - Suspense wrapping KeepAlive -->
  <RouterView v-slot="{ Component }">
    <Suspense>
      <KeepAlive>
        <Transition mode="out-in">
          <component :is="Component" />
        </Transition>
      </KeepAlive>
    </Suspense>
  </RouterView>
</template>

<template>
  <!-- Wrong - KeepAlive outside Transition -->
  <RouterView v-slot="{ Component }">
    <KeepAlive>
      <Transition mode="out-in">
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </Transition>
    </KeepAlive>
  </RouterView>
</template>

Good Code

<template>
  <RouterView v-slot="{ Component }">
    <template v-if="Component">
      <Transition mode="out-in">
        <KeepAlive>
          <Suspense>
            <!-- Main content -->
            <component :is="Component" />

            <!-- Loading state -->
            <template #fallback>
              <div class="route-loading">Loading...</div>
            </template>
          </Suspense>
        </KeepAlive>
      </Transition>
    </template>
  </RouterView>
</template>

With Selective KeepAlive

<template>
  <RouterView v-slot="{ Component, route }">
    <template v-if="Component">
      <Transition :name="route.meta.transition || 'fade'" mode="out-in">
        <KeepAlive :include="cachedViews">
          <Suspense :timeout="200">
            <component :is="Component" :key="route.fullPath" />

            <template #fallback>
              <RouteLoadingSkeleton :route="route" />
            </template>
          </Suspense>
        </KeepAlive>
      </Transition>
    </template>
  </RouterView>
</template>

<script setup>
import { computed } from 'vue';
import { useRoute } from 'vue-router';

const route = useRoute();

// Only cache specific routes
const cachedViews = computed(() => ['Dashboard', 'Profile', 'Settings']);
</script>

Why This Order?

RouterView - Provides the route component via scoped slot
Transition - Needs to wrap what animates (the cached/suspended content)
KeepAlive - Caches the Suspense + component together
Suspense - Directly wraps the async component to handle loading

Important Notes

Vue Router's lazy-loaded route components (via dynamic imports) don't trigger Suspense directly
Only async components within the route component trigger Suspense
Use v-if="Component" to handle the case when no route matches
The :key on the component can force re-render and re-trigger Suspense

Key Points

Always follow the order: RouterView -> Transition -> KeepAlive -> Suspense
Each wrapper serves a specific purpose in this hierarchy
Use mode="out-in" on Transition to prevent overlap during route changes
Consider using route-based keys for fine-grained control over when Suspense triggers

3.6 KiB Raw Blame History