What Is the Role of the lib and utils Directory in Builder.io Agent Native?

The lib and utils directories in BuilderIO/agent-native serve as the backbone of reusable, framework-agnostic code, providing SSR-safe utilities, cross-module libraries, and abstraction layers that enable domain-specific templates to remain focused on their unique business logic.

In the Builder.io Agent Native repository, the lib and utils directories form the foundational layer of the architecture. These folders house pure functions, type helpers, and integration wrappers that are imported across client components, server actions, and test suites. By centralizing this logic, the codebase maintains strict separation of concerns while ensuring that templates like brain, design, and calendar can share common functionality without duplication.

Core Responsibilities of lib and utils

The lib and utils directories fulfill five primary architectural roles within the Agent Native ecosystem.

Shared Helpers and Utilities

These directories provide small, pure-function utilities that can be imported anywhere—client bundles, server-side Nitro routes, actions, or tests. Located in paths like templates/brain/app/lib/utils.ts, these files contain type-checked functions for string parsing, URL construction, safe JSON handling, and navigation helpers.

Cross-Module Libraries

When logic is too domain-specific for a single feature but still reusable across multiple templates, it lives in lib. For example, templates/design/server/lib/provider-api.ts wraps the Builder.io Provider API, offering a thin, consistent interface used by many design-related actions without leaking implementation details.

Third-Party Abstraction Layers

The directories isolate external integrations behind stable internal APIs. Files like templates/calendar/server/lib/google-calendar.ts normalize Google Calendar calls and deliberately avoid side effects such as row deletions. This abstraction allows the rest of the application to remain agnostic of external SDK quirks and credential handling.

Testing Utilities

To keep test suites DRY, lib houses mock factories and deterministic data generators. These utilities enable consistent testing across complex conversion logic, such as verifying Figma-to-HTML transformations without relying on live external services.

Performance-Critical Operations

Low-level operations requiring binary decoding, compression, or media processing reside in specialized lib files. The templates/clips/server/lib/video-remux.ts module leverages FFmpeg libraries (libx264) to encode video streams—a computationally intensive task required by multiple higher-level clip management features.

Architectural Design Principles

The organization of lib and utils reflects deliberate architectural decisions designed to support scalability and maintainability.

Separation of Concerns

By centralizing reusable logic in lib and utils, each template focuses exclusively on domain-specific UI and actions. This delegation prevents business logic from bleeding into presentation layers and ensures that shared responsibilities have a single source of truth.

SSR-Safe Design

Many lib modules are deliberately SSR-safe, containing no direct browser globals like window or document and avoiding heavy client-only dependencies. This design enables the same utilities to be imported in both server-side bundles (Nitro routes) and client bundles (React components) without causing hydration mismatches or runtime errors.

Explicit Dependency Direction

The codebase follows a strict "lib → actions → UI" data flow. lib provides pure utilities, actions import from lib to implement business logic, and UI layers consume actions through shared surfaces like useActionQuery or useActionMutation. This hierarchy prevents circular dependencies and keeps the public action API stable across refactors.

Deliberate Minimalism

Many files contain comments indicating they are "deliberately narrow" in scope. This intentional minimalism reduces the attack surface for security vulnerabilities, improves testability by limiting the number of code paths, and simplifies future refactors by enforcing small, focused public interfaces.

Practical Implementation Examples

The following patterns illustrate how lib and utils are consumed throughout the repository.

Importing Utilities in Client Components

When generating unique identifiers for browser tabs, the Brain template imports a pure utility from its local lib directory:

// File: templates/brain/app/lib/tab-id.ts
import { generateTabId } from '@/lib/tab-id';

// Using the helper in a React hook
export const useTab = () => {
  const tabId = useMemo(() => generateTabId(), []);
  // …
};

Wrapping External APIs in Server Actions

Design-related actions leverage a shared provider wrapper to communicate with Builder.io's backend:

// File: templates/design/server/lib/provider-api.ts
import { getProviderClient } from '@/lib/provider-api';

export async function fetchDesignAssets(designId: string) {
  const client = getProviderClient('design');
  return client.get(`/designs/${designId}/assets`);
}

Processing Media in Low-Level Libraries

Video processing actions import FFmpeg-based utilities from the clips template's server library:

// File: templates/clips/actions/lib/ensure-seekable-video.ts
import { remuxVideo } from '@/server/lib/video-remux';

export async function ensureSeekable(inputPath: string, outputPath: string) {
  await remuxVideo({ input: inputPath, output: outputPath, codec: 'libx264' });
}

Supporting Test Suites with Mock Helpers

The Figma-to-HTML conversion logic relies on shared test utilities to create deterministic mock data:

// File: templates/design/server/lib/figma-node-to-html.test.ts
import { mockFigmaNode } from '@/lib/test-utils';

test('converts Figma node to HTML', () => {
  const node = mockFigmaNode({ type: 'FRAME', children: [] });
  const html = figmaNodeToHtml(node);
  expect(html).toContain('<div');
});

Key Files Across Templates

The following representative files demonstrate the breadth of functionality housed in lib and utils throughout the Agent Native codebase:

• templates/brain/app/lib/utils.ts – Core utility helpers for the Brain app including tab handling, navigation management, and safe JSON parsing.
• templates/design/server/lib/provider-api.ts – Thin wrapper around the Builder.io Provider API used across design actions for consistent data fetching.
• templates/assets/app/lib/utils.ts – Asset-related helpers for URL construction and preview source selection in client-side components.
• templates/calendar/server/lib/google-calendar.ts – Normalized Google Calendar integration with deliberate safety guards and side-effect-free operations.
• templates/clips/server/lib/video-remux.ts – FFmpeg-based video processing utilities using libx264 encoding for cross-template media operations.
• templates/design/server/lib/figma-node-to-html.ts – Converts Figma node structures to HTML snippets, reused by multiple design features for consistent markup generation.

Summary

• The lib and utils directories provide reusable, framework-agnostic building blocks that power the entire Agent Native ecosystem.
• These modules enforce SSR-safe design by avoiding browser-specific globals, enabling seamless use in both Nitro server routes and React client components.
• A strict "lib → actions → UI" dependency flow prevents circular dependencies and maintains API stability across template boundaries.
• Files are intentionally minimal and narrowly scoped to improve security, testability, and long-term maintainability.
• The directories abstract third-party integrations (Figma, Google Calendar, FFmpeg) behind stable internal APIs, insulating domain logic from external SDK changes.

Frequently Asked Questions

What distinguishes the lib directory from the utils directory in Agent Native?

While both directories contain reusable code, lib typically houses larger, domain-specific modules such as API clients and media processors (e.g., video-remux.ts), whereas utils contains smaller, pure helper functions like string parsers and ID generators. The distinction is organizational—utils are atomic building blocks, while lib modules often encapsulate complex logic requiring external dependencies.

Are lib modules safe to import in server-side rendering contexts?

Yes. According to the source code architecture, lib modules are deliberately designed to be SSR-safe. They avoid direct references to browser globals like window or document and exclude heavy client-only dependencies, allowing them to execute without errors in both server-side Nitro bundles and client-side React components.

How does the lib directory prevent circular dependencies in the codebase?

The lib directory sits at the bottom of a strict dependency hierarchy: lib → actions → UI. Utilities in lib have no knowledge of actions or UI components, actions import only from lib, and UI layers import exclusively through action surfaces like useActionQuery. This unidirectional flow ensures that lower-level modules never import from higher-level features, eliminating the possibility of circular references.

Why are some lib files described as "deliberately narrow"?

This phrasing indicates an intentional design choice to limit the surface area of library modules. By keeping interfaces small and focused—such as the Google Calendar integration deliberately avoiding row deletion capabilities—the codebase reduces security risks, simplifies unit testing, and makes future refactoring safer by minimizing the number of dependent code paths that could break during changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}