---
name: workleap-squide
description: |
Squide is a React modular application shell for Workleap web applications. Use this skill when:
(1) Creating or modifying Squide host applications or modules
(2) Registering routes, navigation items, or MSW request handlers
(3) Working with FireflyRuntime, initializeFirefly, or AppRouter
(4) Setting up integrations: TanStack Query, i18next, LaunchDarkly, Honeycomb, MSW, Storybook
(5) Implementing deferred registrations or conditional navigation items
(6) Fetching global public/protected data with usePublicDataQueries/useProtectedDataQueries
(7) Using Squide hooks: useNavigationItems, useRenderedNavigationItems, useIsBootstrapping, useLogger, useEventBusListener, useEventBusDispatcher, useEnvironmentVariable, useFeatureFlag
(8) Implementing error boundaries in modular applications
(9) Questions about modular architecture patterns in React applications
---
# Squide Framework
Squide is a React modular application shell. Use only documented APIs.
## Core Concepts
### Runtime
The `FireflyRuntime` instance is the backbone of a Squide application. Never instantiate directly - use `initializeFirefly()`.
### Modular Registration
Modules register routes, navigation items, and MSW handlers via a registration function. Each module contributes its own configuration, assembled by the host at bootstrapping.
### Public vs Protected Routes
- Routes default to `protected` (rendered under `ProtectedRoutes` placeholder)
- Use `registerPublicRoute()` for public routes (rendered under `PublicRoutes` placeholder)
- Public routes only fetch public global data; protected routes fetch both public and protected data
### Deferred Registrations
Navigation items dependent on remote data or feature flags use two-phase registration:
1. First phase: Register static routes and navigation items
2. Second phase: Return a function from registration to defer navigation items
## Quick Reference
### Host Application Setup
```tsx
// host/src/index.tsx
import { createRoot } from "react-dom/client";
import { FireflyProvider, initializeFirefly } from "@squide/firefly";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { App } from "./App.tsx";
import { registerHost } from "./register.tsx";
const runtime = initializeFirefly({
localModules: [registerHost]
});
const queryClient = new QueryClient();
const root = createRoot(document.getElementById("root")!);
root.render(
);
```
```tsx
// host/src/App.tsx
import { AppRouter, useIsBootstrapping } from "@squide/firefly";
import { createBrowserRouter, Outlet } from "react-router";
import { RouterProvider } from "react-router/dom";
function BootstrappingRoute() {
if (useIsBootstrapping()) {
return Loading...
;
}
return
{({ rootRoute, registeredRoutes, routerProviderProps }) => (
);
}
```
```tsx
// host/src/register.tsx
import { PublicRoutes, ProtectedRoutes, type ModuleRegisterFunction, type FireflyRuntime } from "@squide/firefly";
import { RootLayout } from "./RootLayout.tsx";
export const registerHost: ModuleRegisterFunction = runtime => {
runtime.registerRoute({
element: = runtime => {
runtime.registerRoute({
path: "/page",
element:
);
};
const renderSection: RenderSectionFunction = (elements, key) => (
);
export function RootLayout() {
const navigationItems = useNavigationItems();
const navigationElements = useRenderedNavigationItems(navigationItems, renderItem, renderSection);
return (
<>
{navigationElements}
Loading...
;
return (
);
}
// In App component, set waitForProtectedData
...
```
```tsx
// Public data
const [data] = usePublicDataQueries([{ queryKey: [...], queryFn: ... }]);
...
```
### Deferred Navigation Items
```tsx
export const register: ModuleRegisterFunction = runtime => {
// Always register routes
runtime.registerRoute({ path: "/feature", element: = async runtime => {
if (runtime.isMswEnabled) {
const requestHandlers = (await import("../mocks/handlers.ts")).requestHandlers;
runtime.registerRequestHandlers(requestHandlers);
}
};
```
### Event Bus
```tsx
// Listen
import { useEventBusListener } from "@squide/firefly";
const handleEvent = useCallback((data, context) => { /* ... */ }, []);
useEventBusListener("event-name", handleEvent);
// Dispatch
import { useEventBusDispatcher } from "@squide/firefly";
const dispatch = useEventBusDispatcher();
dispatch("event-name", payload);
```
### Environment Variables
```tsx
// Register at initialization
const runtime = initializeFirefly({
environmentVariables: { apiBaseUrl: "https://api.example.com" }
});
// Or register in module
runtime.registerEnvironmentVariable("key", "value");
// Use
import { useEnvironmentVariable } from "@squide/firefly";
const apiUrl = useEnvironmentVariable("apiBaseUrl");
```
### Feature Flags
```tsx
// Initialize with LaunchDarkly
import { initialize as initializeLaunchDarkly } from "launchdarkly-js-client-sdk";
const ldClient = initializeLaunchDarkly("client-id", { kind: "user", anonymous: true }, { streaming: true });
await ldClient.waitForInitialization(5);
const runtime = initializeFirefly({ launchDarklyClient: ldClient });
// Use
import { useFeatureFlag } from "@squide/firefly";
const isEnabled = useFeatureFlag("feature-key", defaultValue);
```
### Logging
```tsx
import { useLogger } from "@squide/firefly";
const logger = useLogger();
logger.debug("Message");
```
### Error Boundaries
```tsx
// Root error boundary (wraps everything)
runtime.registerRoute({
errorElement: