Type Generation

The @tablecraft/codegen package generates TypeScript types from your TableCraft API metadata, providing full type safety for your frontend code.

Installation

pnpm

# Install as dev dependency
pnpm add -D @tablecraft/codegen

# Or use directly with npx
npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated

npx

Usage

Basic Usage

npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated

This will:

1. Fetch metadata from all tables via /_tables endpoint

2. Generate TypeScript interfaces for each table

3. Create typed adapter factory functions

Options

Option	Alias	Description	Required
--url	-u	Base URL of your TableCraft API	Yes
--out	-o	Output directory for generated files	Yes
--tables	-t	Specific tables to generate (default: all)	No
--header	-H	Custom headers (e.g., -H "Authorization: Bearer token")	No

Examples

Generate All

npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated

Specific Tables

Authenticated

Generated Files

src/generated/
├── index.ts          # Re-exports all types
├── users.ts          # UsersRow, UsersFilters, createUsersAdapter
├── orders.ts         # OrdersRow, OrdersFilters, createOrdersAdapter
├── products.ts       # ProductsRow, ProductsFilters, createProductsAdapter
└── package.json      # Package configuration

Generated Types

Row Interface

Each table generates a Row interface with all column types:

export interface UsersRow extends Record<string, unknown> {
  id: number;
  email: string;
  role: string;
  isActive: boolean;
  createdAt: string | null;
}

Column Type

Filters Interface

Adapter Factory

Using Generated Types

With DataTable

import { DataTable, hiddenColumns } from '@tablecraft/table';
import { createOrdersAdapter, type OrdersRow, type OrdersColumn } from './generated';

function OrdersPage() {
  const adapter = createOrdersAdapter({
    baseUrl: '/api/engine',
  });

  return (
    <DataTable<OrdersRow>
      adapter={adapter}
      hiddenColumns={hiddenColumns<OrdersColumn>(['id', 'tenantId'])}
    />
  );
}

Type-Safe Hidden Columns

The hiddenColumns helper function provides compile-time type checking:

import { hiddenColumns } from '@tablecraft/table';
import type { ProductsColumn } from './generated';

// ✅ Valid - type-checked
hiddenColumns<ProductsColumn>(['id', 'metadata']);

// ❌ Error - 'invalidColumn' is not assignable to ProductsColumn
hiddenColumns<ProductsColumn>(['invalidColumn']);

With Custom Adapter

import { createTableCraftAdapter } from '@tablecraft/table';
import type { UsersRow, UsersFilters } from './generated';

const adapter = createTableCraftAdapter<UsersRow>({
  baseUrl: '/api/engine',
  table: 'users',
});

Benefits

Benefit

Autocomplete

Description

Column names and filter operators appear in your IDE.

Benefit

Type Checking

Description

Catch errors like typos or invalid types at compile time.

Benefit

Refactoring

Description

Rename columns safely across the entire codebase.

Benefit

Documentation

Description

Generated types serve as always-up-to-date documentation.

CI/CD Integration

Add to your package.json to ensure types are always fresh before building:

{
  "scripts": {
    "codegen": "tablecraft-codegen --url $API_URL --out ./src/generated",
    "prebuild": "pnpm codegen"
  }
}