Changes in the definition of async components (defineAsyncComponent)

In Vue 3, the way asynchronous components are defined has undergone significant changes, with defineAsyncComponent becoming the core API. It replaces Vue 2's () => import() syntax, offering more flexible configuration options and error-handling mechanisms.

Basic Usage of defineAsyncComponent

The basic usage of defineAsyncComponent involves returning a Promise through a factory function:

import { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>
  import('./components/MyComponent.vue')
)

This approach is similar to Vue 2's asynchronous components but differs entirely in its underlying implementation. Vue 3's asynchronous components are essentially suspendable components wrapped in Suspense components.

Advanced Configuration Options

defineAsyncComponent accepts a configuration object as a parameter, providing finer-grained control:

const AsyncCompWithOptions = defineAsyncComponent({
  loader: () => import('./components/HeavyComponent.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200, // Delay before showing the loading component
  timeout: 3000, // Timeout duration
  suspensible: false // Whether to use Suspense
})

Handling Loading States

Custom handling for loading and error states can be implemented:

const AsyncWithStatus = defineAsyncComponent({
  loader: () => import('./components/Profile.vue'),
  loadingComponent: {
    template: '<div class="loading">Loading profile...</div>'
  },
  errorComponent: {
    template: '<div class="error">Failed to load profile</div>',
    props: ['error']
  },
  delay: 100,
  timeout: 3000
})

Integration with Suspense

In Vue 3, asynchronous components naturally support Suspense:

<template>
  <Suspense>
    <template #default>
      <AsyncUserProfile />
    </template>
    <template #fallback>
      <div>Loading profile...</div>
    </template>
  </Suspense>
</template>

<script setup>
const AsyncUserProfile = defineAsyncComponent(() => 
  import('./UserProfile.vue')
)
</script>

Error Boundary Handling

Use onErrorCaptured to catch errors in asynchronous component loading:

import { onErrorCaptured } from 'vue'

export default {
  setup() {
    onErrorCaptured((err, instance, info) => {
      console.error('Async component error:', err)
      return false // Prevent the error from propagating further
    })
  }
}

Dynamic Imports and Code Splitting

defineAsyncComponent inherently supports dynamic imports and code splitting:

const DynamicAsyncComp = defineAsyncComponent(() => {
  const page = route.params.page
  return import(`./pages/${page}.vue`)
})

Usage in Composition API

It can be used directly in the <script setup> syntax:

<script setup>
import { defineAsyncComponent } from 'vue'

const AdminPanel = defineAsyncComponent(() =>
  import('./AdminPanel.vue')
)
</script>

Performance Optimization Tips

User experience can be optimized with preloading strategies:

const PreloadableComponent = defineAsyncComponent({
  loader: () => import('./ChartComponent.vue'),
  loadingComponent: LoadingIndicator,
  onLoad() {
    // Execute after the component loads
    preloadRelatedComponents()
  }
})

function preloadRelatedComponents() {
  // Preload related components
  import('./ChartTooltip.vue')
  import('./ChartLegend.vue')
}

Integration with Routing

Combine with Vue Router:

const router = createRouter({
  routes: [
    {
      path: '/dashboard',
      component: defineAsyncComponent(() => 
        import('./views/Dashboard.vue')
      )
    }
  ]
})

Server-Side Rendering Considerations

Special handling is required in SSR environments:

const SSRCompatibleComponent = defineAsyncComponent({
  loader: () => import('./SSRComponent.vue'),
  suspensible: false, // Disable Suspense
  serverPrefetch() {
    // SSR prefetch logic
    return fetchData()
  }
})

Testing Asynchronous Components

Asynchronous behavior must be handled during testing:

test('renders async component', async () => {
  const wrapper = mount(defineAsyncComponent({
    loader: () => Promise.resolve({
      template: '<div>Test Content</div>'
    })
  }))
  
  await flushPromises()
  expect(wrapper.text()).toContain('Test Content')
})

Practical Use Cases

Modular loading in large-scale applications:

// Load components on user interaction
function loadOnDemand() {
  const Modal = defineAsyncComponent(() => 
    import('./Modal.vue')
  )
  // Use the Modal component dynamically
}

Integration with State Management

Use with Pinia or Vuex:

const StoreDependentComponent = defineAsyncComponent({
  loader: async () => {
    const store = useUserStore()
    await store.fetchUser()
    return import('./UserProfile.vue')
  }
})

Type Safety (TypeScript)

Full type support is available in TypeScript:

interface AsyncComponentProps {
  userId: number
}

const TypedAsyncComponent = defineAsyncComponent({
  loader: (): Promise<{ default: DefineComponent<AsyncComponentProps> }> => 
    import('./TypedComponent.vue')
})