@teliagen/vite-plugin

Vite plugin for Teliagen client code generation.

Overview

@teliagen/vite-plugin generates typed client code from Teliagen server metadata:

• Automatic Generation – Generates on dev server start
• Hot Reload – Regenerates on metadata changes
• Typed Hooks – React hooks with full TypeScript inference
• Multiple Sources – Connect to multiple backend services
• Local & Remote – Read from local files or fetch from servers

Installation

npm install -D @teliagen/vite-plugin
# or
pnpm add -D @teliagen/vite-plugin

Quick Start

Local Backend (Monorepo)

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { teliagen } from '@teliagen/vite-plugin';

export default defineConfig({
  plugins: [
    react(),
    teliagen({
      name: 'main',
      mode: 'local',
      path: '../server'  // Path to backend project
    })
  ]
});

Remote Backend

// vite.config.ts
import { teliagen } from '@teliagen/vite-plugin';

export default defineConfig({
  plugins: [
    teliagen({
      name: 'api',
      mode: 'remote',
      url: 'http://localhost:3000',
      endpoint: '/teliagen/metadata'
    })
  ]
});

Configuration

interface TeliagenViteOptions {
  // Identity
  name?: string;              // Source name (default: 'main')
  
  // Mode
  mode?: 'local' | 'remote';  // How to fetch metadata
  
  // Local mode options
  path?: string;              // Path to backend project
  metadataPath?: string;      // Direct path to metadata.json
  
  // Remote mode options
  url?: string;               // Backend URL
  endpoint?: string;          // Metadata endpoint (default: '/teliagen/metadata')
  
  // Generation
  strategy?: 'physical' | 'virtual';  // Output strategy
  outputDir?: string;         // Output directory (default: '.teliagen-client')
  
  // Error handling
  optional?: boolean;         // Don't fail if source unavailable
}

Multiple Sources

Connect to multiple backend services:

// vite.config.ts
import { teliagen } from '@teliagen/vite-plugin';

export default defineConfig({
  plugins: [
    teliagen([
      {
        name: 'main',
        mode: 'local',
        path: '../main-server'
      },
      {
        name: 'auth',
        mode: 'remote',
        url: 'http://localhost:3001',
        optional: true  // Don't fail if auth server is down
      },
      {
        name: 'payments',
        mode: 'remote',
        url: process.env.PAYMENTS_API_URL,
        optional: true
      }
    ])
  ]
});

Generated Output

The plugin generates typed client code:

.teliagen-client/
├── main/
│   ├── index.ts              # Barrel exports
│   ├── hooks/
│   │   ├── useLogin.ts       # Typed React hook
│   │   ├── useRegister.ts
│   │   └── useListUsers.ts
│   ├── schemas/
│   │   ├── LoginInput.ts
│   │   └── UserOutput.ts
│   └── types/
│       └── index.ts
├── auth/
│   └── ...
└── payments/
    └── ...

Generated Hook Example

// .teliagen-client/main/hooks/useLogin.ts
import { useTeliagenAction } from '@teliagen/react';

export interface LoginInput {
  email: string;
  password: string;
}

export interface LoginOutput {
  user: {
    id: string;
    email: string;
    name?: string;
  };
  token: string;
}

export function useLogin() {
  return useTeliagenAction<LoginInput, LoginOutput>(
    'login',
    { module: 'auth', provider: 'AuthActions' }
  );
}

Using Generated Code

// Import generated hooks
import { useLogin, useListUsers, useCreateUser } from '.teliagen-client/main';

function LoginPage() {
  const login = useLogin();
  
  return (
    <button onClick={() => login.execute({ 
      email: '[email protected]', 
      password: 'secret' 
    })}>
      Login
    </button>
  );
}

function UserList() {
  const { data, isLoading } = useListUsers({ page: 1, limit: 10 });
  
  if (isLoading) return <p>Loading...</p>;
  
  return (
    <ul>
      {data?.users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

TypeScript Configuration

Add the generated directory to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      ".teliagen-client/*": ["./.teliagen-client/*"]
    }
  },
  "include": [
    "src",
    ".teliagen-client"
  ]
}

Strategies

Physical (Default)

Generates actual files on disk:

teliagen({
  strategy: 'physical',  // default
  outputDir: '.teliagen-client'
})

Pros:

• IDE support out of the box
• Can be committed to git
• Works with any bundler

Cons:

• Files on disk

Virtual

Uses Vite virtual modules (no files on disk):

teliagen({
  strategy: 'virtual'
})

Pros:

• No generated files
• Cleaner project structure

Cons:

• Requires Vite
• IDE may need additional config

Watch Mode

In development, the plugin watches for metadata changes:

// Local mode: Watches .teliagen/metadata.json
// When backend regenerates metadata, client code updates

// Remote mode: Manual refresh needed (restart dev server)

Environment-Based Config

// vite.config.ts
export default defineConfig(({ mode }) => ({
  plugins: [
    teliagen({
      name: 'api',
      mode: mode === 'development' ? 'local' : 'remote',
      path: mode === 'development' ? '../server' : undefined,
      url: mode === 'production' ? process.env.API_URL : undefined
    })
  ]
}));

Error Handling

teliagen({
  name: 'auth',
  mode: 'remote',
  url: 'http://auth-service:3001',
  optional: true  // Log warning instead of failing
})

When optional: true:

• Missing local metadata: Skips silently
• Unreachable remote: Logs warning, continues build
• Useful for services that may be down during development

Integration with Backend

Your backend should expose metadata via ClientContractSync or ServerContractSync:

// teliagen.config.ts (backend)
import { defineConfig, ClientContractSync } from '@teliagen/commons';

export default defineConfig({
  features: [
    ClientContractSync({
      endpoint: '/teliagen/metadata',
      allowInProduction: false
    })
  ]
});

Requirements

• Vite >= 5.0.0
• Node.js >= 18.0.0

Related Packages

• @teliagen/client – HTTP transport
• @teliagen/react – React hooks

Documentation

For full documentation, visit docs.teliagen.org.

License

Apache-2.0