Build your first “Hello, world” extension
Learn how to create your first extension and run it in Airtable. Make sure to follow the steps in the Getting started guide first.
Set up a new Airtable base
To start, make a new Airtable base from scratch. Its name doesn't matter, but we'll call it “Extensions!” in this guide.
Note that we're just creating a new base for the purposes of this guide—you can build extensions in any base you already have, as long as it's in a Pro or Enterprise workspace.
Currently, extensions start off as “belonging to” a single Airtable base. Distributing extensions to additional bases can be done by following the "Run in multiple bases" guide.
Now that we have a base, it's time to create our extension.
Create a new extension
Open the Extensions dashboard by clicking the “Extensions” button at the top-right of the screen. From there, click “Install an extension”, and then “Build a custom extension.
Now it's time to give our new extension a name. We'll call it “Hello Extensions.
Click “Create extension” to continue.
Next, you’ll need to follow the on-screen instructions. First, open your terminal. Then, follow the instructions to install the Airtable Blocks command line tool.
To check that you have the correct version of blocks-cli, run block
in the terminal. You should
see instructions for using blocks-cli, which begins with Usage: block <command> [options]
.
The next screen will have you running block init
with some additional arguments. Once you’ve
entered your Airtable personal access token (with block:manage
scope), the block init
command will install dependencies and then your
project will be ready! Run cd hello_extensions
, then block run
(as it says).
In the terminal output, you’ll see something like “Your block is running locally at
http://localhost:9000
”. It will automatically copy the URL to your clipboard.
After switching back to Airtable, paste the localhost URL (or enter manually) in the input field, then click "Start editing extension".
The first time you do this, you may need to tell your browser that https://localhost:9000
is safe to
visit. Follow the on-screen instructions to do this. You may need to restart your browser. After
restarting the browser, go back to the base, click your extension's name, then click "Edit extension".
If you've done this correctly, you'll see your extension appear!
Open frontend/index.js
in your text editor and try changing the text from “Hello world 🚀” to
something else, like “Goodbye, Earth! 🌍”. When you save the file, the extension server will update and
your extension should refresh in the browser automatically.
Great! We have our extensions development environment set up.
You can stop the server at any time by pressing Control-C
in the terminal window that's running
block run
.
This extension is only really present in development. That’s useful while you’re working. But if you turn off your development server and refresh the page, the extension will disappear. And if another collaborator on your base shows up, all they'll see is this empty extension. Next, we'll see how to release our extension.
Releasing your extension
While you're working on code, you don't want to show it off until it's ready. But at some point, it will be ready for the rest of your base collaborators to see, and then it's time to release it!
When you're ready to release your extension, run block release
. This will build your extension's code and
upload it to Airtable's servers. Airtable's servers will automatically take care of releasing your
extension.
Now, refresh the page in the browser. You’ll see your extension is still there! You can even turn your development server off and the extension will still be there (though you can leave it running if you want). You can also try inviting a collaborator to your base and they should be able to see your extension.
Onward!
We’ve built “Hello, extensions”. You’ve gotten your computer set up, seen how to create a new extension, how to make changes to it, and how to release it.
Next: learn how to build a to-do list extension →
Appendix: files and directory structure
If you look around your newly-created hello_extensions
folder, you'll see a directory structure like
this:
hello_extensions├── .block/│ └── remote.json├── .eslintrc.js├── .gitignore├── block.json├── build/├── frontend/│ └── index.js├── node_modules/├── package.json└── package-lock.json
Not seeing the files that start with .? Try $ ls -a
to show them.
Let's talk about what each of these files are.
.block/remote.json
describes some metadata for your extension. The block command uses this to know which extension you're developing. You shouldn't need to edit this file directly..eslintrc.js
describes some default rules for ESLint, which is an optional command (npm run lint
) you can run that has recommendations for code style and best practices. You shouldn't need to edit this file for this guide..gitignore
describes the files that Git should ignore. You shouldn't need to edit this file for this guide.block.json
describes the configuration for your extension. Right now, this is how you specify which file to use as the frontend entry point for your extension. In the future, we may add additional properties to this file.build/
is a directory that contains built files. You shouldn’t edit files here.frontend/index.js
is the entry point to your project (as described in block.json). You’ll do most of your work in this folder.node_modules/
is a standard in JavaScript projects. It is where all of your dependencies, such as React, are installed. You shouldn’t make any changes in this folder.package.json
is a file that's standard in most JavaScript projects. You'll use it to describe your extension's dependencies. For example, React is a dependency, which you can see in package.json.package-lock.json
is a file that npm uses to install your dependencies. You shouldn’t make any changes to this file.