exports

Exports & Barrel Files

Standards for module exports and barrel files in the portal app.

Core Principle

Named exports only. No flat wildcards. No default exports in barrels.

Turbopack and modern bundlers handle named exports better for tree-shaking. Flat wildcard export * forces bundlers to include everything and breaks cache invalidation.

Exception: export * as Name is allowed for compound components (Dialog, Menu, etc.) to create namespaces.

Barrel File Structure

Every barrel file follows this structure:

/* eslint-disable */

// Section Name

export { Thing, type ThingProps } from "./thing";
export { Other } from "./other";

// Another Section

export { More } from "./more";

Rules

1. ESLint disable at top - Barrel files intentionally re-export
2. Section comments - Group related exports with // Section Name
3. Alphabetical within sections - Sort exports alphabetically within each group
4. Types with values - Export types alongside their values: export { Foo, type FooProps }
5. One line per file - Each source file gets one export line

Section Naming

Use these section names consistently:

Examples

Component Barrel

/* eslint-disable */

// Components

export { ActionCard } from "./action-card";
export { ActionList } from "./action-list";
export { ActionPicker } from "./action-picker";

State/Domain Barrel

/* eslint-disable */

// Store

export { useNodesSelection, useNodesSelectionArray } from "./store";

// Types

export {
  type NodeOwner,
  type NodePermissionRow,
  type NodeRow,
  type NodeWithMeta,
  transformNode,
} from "./types";

UI Library Barrel

For compound components (Dialog, Menu, etc.), export as namespaces using export * as:

/* eslint-disable */

// Simple Components

export { Badge, type BadgeProps } from "./badge";
export { Button, type ButtonProps } from "./button";
export { Input, type InputProps } from "./input";

// Compound Components (namespace exports)

export * as Accordion from "./accordion";
export * as Alert from "./alert";
export * as Dialog from "./dialog";
export * as Menu from "./menu";

// Layout

export { AbsoluteCenter } from "./absolute-center";
export { Group } from "./group";

Note: Compound components use export * as Name to create namespaces (e.g., Dialog.Root, Dialog.Content). This is the ONE exception to the "no wildcards" rule - it creates a namespace, not a flat re-export.

What NOT to Do

No Flat Wildcards

// WRONG - flat wildcard re-exports everything
export * from "./button";
export * from "./card";

// RIGHT - named exports
export { Button, type ButtonProps } from "./button";

// RIGHT - namespace export for compound components
export * as Card from "./card";

No Default Exports in Barrels

// WRONG
export { default as Button } from "./button";

// RIGHT - source file should use named export
export { Button } from "./button";

No Aliasing (Unless Necessary)

// WRONG - unnecessary alias
export { Button as ButtonComponent } from "./button";

// RIGHT
export { Button } from "./button";

// OK - resolving actual name conflict
export { ActionList as ActionListComponent } from "./action-list";

No Mixed Concerns

// WRONG - implementations don't belong in barrel
export { Button } from "./button";
export const DEFAULT_SIZE = "md"; // NO - this belongs in a constants file

// RIGHT - barrel only re-exports
export { Button } from "./button";
export { DEFAULT_SIZE } from "./constants";

When to Create a Barrel

Always. Every directory with exportable code gets an index.ts.

Index Files Are ONLY Barrels

An index.ts file must ONLY contain re-exports. No implementations.

If you find an index.ts with actual code (functions, constants, types defined inline), split it up:

1. Move implementations to separate files (e.g., utils.ts, types.ts, constants.ts)
2. Make index.ts a pure barrel that re-exports from those files

// WRONG - index.ts with implementation
export const FOO = "bar";
export function doThing() { ... }
export interface MyType { ... }

// RIGHT - index.ts as pure barrel
export { FOO } from "./constants";
export { doThing } from "./utils";
export type { MyType } from "./types";

Import Conventions

When importing from barrels:

// GOOD - import from barrel
import { Button, Card, Dialog } from "@/components/ui";
import { useNodes, useNodeMutations } from "@/lib/state";

// AVOID - bypassing barrel for public exports
import { Button } from "@/components/ui/button";

// OK - importing internal/non-exported utilities
import { internalHelper } from "@/components/ui/button/helpers";

Instructions

When creating or modifying barrel files:

1. Add /* eslint-disable */ at top
2. Group exports into logical sections with // Section Name
3. Use named exports only - no flat export * (exception: export * as Name for compound component namespaces)
4. Sort exports alphabetically within sections
5. Include types with their values on same line
6. One export statement per source file