v0.4.0GitHub—

docs / guides / frameworks

Framework integrations

Mount one instance on the client and clean it up with the view.

Install the npm package into your application first, as described in Installation. These recipes assume the listed framework is already part of your project. Swarm Troopers does not install React, Vue, Svelte, Astro, Angular, or a router.

##React

Create the instance in an effect after content mounts. Keep the root stable, and return cleanup. Development Strict Mode can exercise setup and cleanup twice; the cleanup is essential.

jsx
import { useEffect } from 'react';
import { create, controls } from 'swarmtroopers';

export function SwarmTroopersOverlay() {
  useEffect(() => {
    const swarmtroopers = create({ root: 'main', auto: true });
    controls(swarmtroopers);
    return () => swarmtroopers.destroy();
  }, []);
  return null;
}

Use React’s effect lifecycle to synchronize with an external DOM system. Do not create Swarm Troopers during render.

##Next.js App Router

Use a client component. A pathname dependency recreates the instance after route changes; ensure the target page content has mounted before starting, especially with streamed or suspended content. For content arriving later, call refresh() after it becomes available.

jsx
'use client';
import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
import { create } from 'swarmtroopers';

export default function SwarmTroopersOverlay() {
  const pathname = usePathname();
  useEffect(() => {
    const swarmtroopers = create({ root: 'main', auto: true });
    return () => swarmtroopers.destroy();
  }, [pathname]);
  return null;
}

See the framework’s usePathname reference for routing constraints in your application.

##Vue and Nuxt

vue
<script setup>
import { onMounted, onBeforeUnmount } from 'vue';
import { create } from 'swarmtroopers';

let swarmtroopers;
onMounted(() => {
  swarmtroopers = create({ root: 'main', auto: true });
});
onBeforeUnmount(() => swarmtroopers?.destroy());
</script>

Vue lifecycle hooks keep browser work outside server rendering. In Nuxt, put this in a .client.vue component or mount it inside <ClientOnly>. If your router keeps a layout mounted, subscribe to navigation after its DOM update and recreate or refresh deliberately; mounting a second global instance is not navigation handling.

##Svelte and SvelteKit

svelte
<script>
  import { onMount } from 'svelte';
  import { create } from 'swarmtroopers';

  onMount(() => {
    const swarmtroopers = create({ root: 'main', auto: true });
    return () => swarmtroopers.destroy();
  });
</script>

The synchronous onMount callback returns teardown. Do not make this callback async: returning a Promise is not the cleanup function. In persistent layouts, handle later navigation separately.

##Astro and client navigation

A plain Astro page can use a processed client script after its content. When using the client router, create on astro:page-load and destroy before the document is swapped. Keep this script registered once.

astro
<script>
  import { create, type SwarmTroopers } from 'swarmtroopers';
  let swarmtroopers: SwarmTroopers | undefined;

  document.addEventListener('astro:page-load', () => {
    swarmtroopers?.destroy();
    swarmtroopers = create({ root: 'main', auto: true });
  });
  document.addEventListener('astro:before-swap', () => {
    swarmtroopers?.destroy();
    swarmtroopers = undefined;
  });
</script>

The Astro navigation lifecycle describes when the new document is ready.

##Angular

Initialize after view creation, guard server rendering, and clean up at destruction. In a zone-based application, run the animation outside Angular’s zone to avoid scheduling change detection for each animation frame.

typescript
import { isPlatformBrowser } from '@angular/common';
import {
  AfterViewInit, Component, NgZone, OnDestroy, PLATFORM_ID, inject,
} from '@angular/core';
import { create, type SwarmTroopers } from 'swarmtroopers';

@Component({ selector: 'app-swarmtroopers', template: '' })
export class SwarmTroopersOverlay implements AfterViewInit, OnDestroy {
  private zone = inject(NgZone);
  private platform = inject(PLATFORM_ID);
  private swarmtroopers?: SwarmTroopers;

  ngAfterViewInit() {
    if (!isPlatformBrowser(this.platform)) return;
    this.zone.runOutsideAngular(() => {
      this.swarmtroopers = create({ root: 'main', auto: true });
    });
  }

  ngOnDestroy() { this.swarmtroopers?.destroy(); }
}

See Angular lifecycle and NgZone. With any framework, finish rendering important content first and avoid two animation systems controlling the same element.