An extremely simple Airtable client for JavaScript.
yarn add luft
// or
npm install luft
An example that utilizes most options:
import { initialize, get } from 'luft';
initialize({
baseId: '<your base id>',
apiKey: '<your api key>',
});
const getUpcomingShows = async () => {
let records;
try {
records = await get('Shows', {
sort: [{ field: 'Date', direction: 'desc' }],
populate: [
{
path: 'Venue',
from: 'Venues',
multi: false,
fields: ['Address', 'City', 'Name'],
},
{
path: 'With',
from: 'Bands',
multi: true,
fields: ['Name']
},
],
filter: 'IS_AFTER({Date}, NOW())',
toObject: true,
});
} catch (err) {
// Error handling
}
return records;
};
luft is a simplifying wrapper around airtable.js - the aim is not to reinvent the wheel but to simplify some things to allow for lightweight more implementations. You can use getBase
as an escape hatch if necessary to use the full raw functionality.
All record getXYZ
functions take the table name as the first param and support the following optional params:
fields
- an array of fieldnames to selectsort
- a list of sort objects with afield
and optionaldirection
keys (see api docs)filter
- a filter formula (see the Formula field reference and api docs)populate
- an array of population specs, see PopulationtoObject
- boolean, return raw airtable.js records or plain objects with all keys converted to camelCase - defaultfalse
Initializes your Airtable instance. Only one base is supported.
import { initialize } from 'luft';
initialize({
baseId: '<your base id>',
apiKey: '<your api key>',
});
// Now do things, see below
Visit your account page to get your API key.
It's recommended to use environment variables here for security and flexibility.
import { get } from 'luft';
// initialize...
const shows = await get('Shows', {
// See common parameters
});
import { getById } from 'luft';
// initialize...
const shows = await getById('Shows', {
recordId: 'abc123',
// See common parameters
});
For example to use Airtable as a rudimentary CMS:
import { getByKey } from 'luft';
// initialize...
const homepageContent = await getById('Content', {
key: 'home',
field: 'page',
// See common parameters
});
(protip: the rich text field type is Markdown)
This is where luft really goes 💨.
Pass an array of population specs to population
to get linked fields from other tables.
import { getByKey } from 'luft';
// initialize...
await get('Shows', {
populate: [
{
path: 'Venue',
from: 'Venues',
multi: false,
fields: ['Address', 'City', 'Name'],
},
{
path: 'With',
from: 'Bands',
multi: true,
fields: ['Name']
},
],
// See common parameters, toObject will convert the populated fields as well
});
A population spec has:
path
- the field that you want to populatefrom
- the table to get it frommulti
- whether to get one or multiple records (we can't tell this from the record sadly), you can safely leave this totrue
when in doubt to always get an array of resultsfields
- an array of fieldnames to select in the target record
It is currently only possible to populate one level deep. (create an issue of you need more)
luft uses airtable.js under the hood, you can get the raw base
to write your own logic:
import { getBase } from 'luft';
// initialize...
const base = getBase()
base('Shows').destroy(['rec123ABC'])
Runs the project in development/watch mode. The project will be rebuilt upon changes.
Bundles the package to the dist
folder.
The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).
Runs the test watcher (Jest) in an interactive mode.
This project was bootstrapped with TSDX.
Some inspiration taken from https://github.com/Arro/airtable-json