tessl/npm-single-spa

The router for easy microfrontends that enables multiple frameworks to coexist on the same page.

—

Pending

Overview

Eval results

Files

Navigation & Routing

Name: tessl/npm-single-spa
Author: tessl

Navigation utilities and routing integration for managing URL changes and programmatic navigation between microfrontends.

Capabilities

Navigate to URL

Programmatically navigate to a URL within the single-spa application. This function integrates with the browser's history API and triggers appropriate application mounting/unmounting.

/**
 * Navigate to a URL programmatically
 * @param obj - URL string or event object with currentTarget.href
 * @param opts - Optional navigation options
 */
function navigateToUrl(
  obj: string | { currentTarget: { href: string }, preventDefault: any },
  opts?: Object
): void;

Usage Examples:

import { navigateToUrl } from "single-spa";

// Navigate with URL string
navigateToUrl("/products/123");

// Navigate from click event
function handleNavigation(event) {
  navigateToUrl(event); // Automatically extracts URL from event.currentTarget.href
}

// Navigate from anchor element
const link = document.querySelector('a[href="/dashboard"]');
navigateToUrl(link);

// Navigate with options
navigateToUrl("/analytics", { 
  state: { from: "dashboard" },
  replace: true 
});

Trigger Application Changes

Manually triggers the process of mounting and unmounting applications based on the current URL. Useful for forcing a re-evaluation of which applications should be active.

/**
 * Manually trigger application mount/unmount based on current route
 * @returns Promise that resolves when all application changes are complete
 */
function triggerAppChange(): Promise<any>;

Usage Examples:

import { triggerAppChange } from "single-spa";

// Force re-evaluation of active applications
await triggerAppChange();

// Trigger after dynamic route changes
function updateUserPermissions() {
  // Update user permissions logic
  // Force single-spa to re-evaluate which apps should be active
  triggerAppChange();
}

// Use in error recovery
async function recoverFromError() {
  try {
    await triggerAppChange();
    console.log("Applications successfully re-evaluated");
  } catch (error) {
    console.error("Failed to trigger application changes:", error);
  }
}

Patch History API

Patches the browser's history API to integrate with single-spa routing. This is automatically called by start() but can be called manually if needed.

/**
 * Patch browser history API for single-spa integration
 * @param opts - Optional configuration options
 */
function patchHistoryApi(opts?: StartOpts): void;

interface StartOpts {
  urlRerouteOnly?: boolean;
}

Usage Examples:

import { patchHistoryApi } from "single-spa";

// Patch history API manually (usually not needed)
patchHistoryApi();

// Patch with URL-only rerouting
patchHistoryApi({ urlRerouteOnly: true });

Custom Event Integration

Single-spa emits custom events during navigation and application lifecycle changes:

// Listen for single-spa routing events
window.addEventListener("single-spa:routing-event", (event) => {
  console.log("Navigation occurred:", event.detail);
});

// Listen for application lifecycle events
window.addEventListener("single-spa:app-change", (event) => {
  console.log("Applications changed:", event.detail);
});

Routing Integration Patterns

Hash-based Routing

import { registerApplication, navigateToUrl } from "single-spa";

// Register applications for hash-based routing
registerApplication({
  name: "products",
  app: () => import("./products/products.app.js"),
  activeWhen: (location) => location.hash.startsWith("#/products")
});

// Navigate using hash
navigateToUrl("#/products/electronics");

Query Parameter Routing

import { registerApplication, navigateToUrl } from "single-spa";

// Route based on query parameters
registerApplication({
  name: "modal",
  app: () => import("./modal/modal.app.js"),
  activeWhen: (location) => {
    const params = new URLSearchParams(location.search);
    return params.has("modal");
  }
});

// Navigate with query parameters
navigateToUrl("/dashboard?modal=user-settings");

Nested Route Management

import { registerApplication, navigateToUrl } from "single-spa";

// Parent application
registerApplication({
  name: "admin",
  app: () => import("./admin/admin.app.js"),
  activeWhen: "/admin"
});

// Child applications within admin
registerApplication({
  name: "admin-users",
  app: () => import("./admin/users/users.app.js"),
  activeWhen: "/admin/users"
});

registerApplication({
  name: "admin-settings",
  app: () => import("./admin/settings/settings.app.js"),
  activeWhen: "/admin/settings"
});

// Navigate between nested routes
navigateToUrl("/admin/users/profile/123");

Error Handling

import { navigateToUrl, addErrorHandler } from "single-spa";

// Handle navigation errors
addErrorHandler((error) => {
  if (error.message.includes("navigation")) {
    console.error("Navigation error:", error);
    // Fallback navigation
    navigateToUrl("/error");
  }
});

// Safe navigation with error handling
function safeNavigate(url) {
  try {
    navigateToUrl(url);
  } catch (error) {
    console.error("Navigation failed:", error);
    // Handle navigation failure
  }
}

Install with Tessl CLI