Eloquent Packages

The @elqnt/* npm packages provide shared code, types, and utilities used across all Eloquent frontend applications.

Package Overview

Installation

npm install @elqnt/api-client @elqnt/types @elqnt/entity

Package Structure

Each package follows a consistent structure:

packages/{name}/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # Public exports
│   ├── models/           # TypeScript types (from tygo)
│   │   └── *.ts
│   ├── api/              # API client functions
│   │   └── *.ts
│   └── hooks/            # React hooks (if applicable)
│       └── use-*.ts
└── dist/                 # Built output

Using Packages

API Client

// Browser-side
import { browserApiRequest } from "@elqnt/api-client/browser";

const result = await browserApiRequest("/api/v1/agents", {
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Server-side (SSR)
import { createServerClient } from "@elqnt/api-client/server";

const client = createServerClient({
  gatewayUrl: process.env.API_GATEWAY_URL!,
  jwtSecret: process.env.JWT_SECRET!,
});

const result = await client.get("/api/v1/agents", { orgId });

Type Imports

// Import types (use type keyword)
import type { User, Org, ResponseMetadata } from "@elqnt/types";
import type { EntityRecord, EntityDefinition } from "@elqnt/entity/models";
import type { Agent, AgentTool } from "@elqnt/agents/models";

Entity Hooks

import { useEntities } from "@elqnt/entity/hooks";

function useCustomers() {
  const { queryRecords, createRecord, loading, error } = useEntities({
    baseUrl: config.apiGatewayUrl,
    orgId: config.orgId,
  });

  // ... custom logic
}

Publishing Packages

Version Bump

cd packages/{name}
npm version patch  # or minor, major

Publish to npm

npm publish --access public

GitHub Release

gh release create @elqnt/{name}@1.2.3 \
  --title "@elqnt/{name} v1.2.3" \
  --notes "- Added new feature\n- Fixed bug"

Updating Consumer Apps

After publishing:

cd apps/eloquent-app
npm update @elqnt/{name}

Type Generation

Types are generated from Go using tygo:

cd /Users/ahmed/workspace/eloquent/eloquent
make generate

This updates TypeScript types in all packages based on Go source types.

Best Practices

1. Use type imports - import type { ... } for types-only imports
2. Don't duplicate types - Always use generated types from packages
3. Version carefully - Breaking changes require major version bump
4. Document changes - Update changelog with each release
5. Test before publish - Run npm run type-check before publishing

Next Steps

• Type System - Type generation from Go
• Frontend Apps - Using packages in apps
• API Gateway - API client configuration