airtable-ts-codegen

Autogenerate TypeScript definitions for your Airtable base

Usage

Run with:

AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 npx airtable-ts-codegen

This will output a file app1234.ts that exports all the table definitions

Generate from a specific view

You can also generate TypeScript definitions based on a specific view, which will only include the fields visible in those views:

AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 AIRTABLE_VIEW_IDS=viw1234,viw5678 npx airtable-ts-codegen

This will output a file app1234.ts that exports table definitions with only the fields visible in the specified views.

Attachment type (unstable)

By default, multipleAttachments fields are typed as string[] (array of URLs). To get full attachment metadata (id, filename, size, type, etc.), set UNSTABLE_AIRTABLE_ATTACHMENT_TYPE=Attachment:

AIRTABLE_API_KEY=pat1234.abcd AIRTABLE_BASE_ID=app1234 UNSTABLE_AIRTABLE_ATTACHMENT_TYPE=Attachment npx airtable-ts-codegen

This will generate Attachment[] instead of string[] for attachment fields, giving you access to the full attachment object with properties like id, url, filename, size, type, width, height, and thumbnails.

Note: This option is unstable and may change or be removed in future versions.

Example generated file

/* DO NOT EDIT: this file was automatically generated by airtable-ts-codegen */
/* eslint-disable */
import { Item, Table } from 'airtable-ts';

export interface Task extends Item {
  id: string,
  name: string,
  status: string,
  dueAt: number,
  isOptional: boolean,
}

export const tasksTable: Table<Task> = {
  name: 'Tasks',
  baseId: 'app1234',
  tableId: 'tbl5678',
  mappings: {
    name: 'fld9012',
    status: 'fld3456',
    dueAt: 'fld7890',
    isOptional: 'fld1234',
  },
  schema: {
    name: 'string',
    status: 'string',
    dueAt: 'number',
    isOptional: 'boolean',
  },
};

You can then easily use this with airtable-ts, for example:

import { AirtableTs } from 'airtable-ts';
import { tasksTable } from './generated/app1234';

const db = new AirtableTs({ apiKey: 'pat1234.abcdef' });
const allTasks = await db.scan(tasksTable);

// You now have all the benefits of airtable-ts, without having to define schemas manually 🎉

Contributing

Pull requests are welcomed on GitHub! To get started:

1. Install Git and Node.js
2. Clone the repository
3. Install dependencies with npm install
4. Run npm run test to run tests
5. Build with npm run build
6. Run the local version with npm start

Releases

Versions follow the semantic versioning spec.

To release:

1. Use npm version <major | minor | patch> to bump the version
2. Run git push --follow-tags to push with tags
3. Wait for GitHub Actions to publish to the NPM registry.