Skip to content
First
Esc
↑↓navigate↵open⌘Jpreview
On this page

Get started

Create a First app, run it on WordPress on your machine, and call its REST API.

In this guide we create a notes app, start it on a local WordPress site, add a note, and read it back through the REST API. It takes about five minutes.

You need Node.js 22 or later and npm. You don’t need Docker, PHP or a database. First downloads a local WordPress for you.

Create the app

Run the creator with a new directory name:

npm create @spacefast/first my-app
cd my-app

You should see:

Created my-app.

  cd "my-app"
  npm run dev

The directory holds one config file, first.config.ts:

notes is a collection: WordPress stores each note as a post. Anyone can read notes. Only WordPress editors can change them.

Check the config

npm run check

You should see:

ok: 1 collections, 0 tables, 0 user projections, 0 globals, 0 hooks, 0 actions (6ms)

check compiles the config and writes nothing. If the config has a problem, it prints the file, the line and a diagnostic code instead.

Start the site

npm run dev

The first start downloads WordPress and takes about a minute. When it is ready, you should see lines like these:

built 1 collections, 0 tables, 0 user projections, 0 globals, 0 hooks, 0 actions -> first/dist/wp-content (new migrations first/_generated/migrations/0001_init.sql) in 11s
WordPress version: 7.1.4
Plugin 'action-scheduler' activated.
Plugin 'mcp-adapter' activated.
Plugin 'secure-custom-fields' activated.
Plugin 'two-factor' activated.
Plugin 'first-runtime' activated.
Plugin 'first-identity' activated.
Plugin 'first-app-my-app' activated.
Plugin 'first-admin' activated.
Website:   http://localhost:9187/
WordPress: http://localhost:9187/wp-admin/
Plugins:   http://localhost:9187/wp-admin/plugins.php
App:       http://localhost:9187/wp-content/plugins/first-app-my-app/public/index.html
First Admin: http://localhost:9187/first-admin/

Your port can differ. The next line prints a local admin login. Use it only on your machine. Keep this terminal open. dev rebuilds the app when you save first.config.ts.

Add a note

Open a second terminal in my-app. Insert a note with the CLI:

npx first insert notes '{"title":"Hello"}'

You should see the new row:

{"data":[{"id":5,"title":"Hello","body":null,"status":"published","publishedAt":"2026-11-09T04:26:14.000Z"}]}

You can also add notes in First Admin, the admin at /wp-admin/new/, or in classic wp-admin. Sign in with the login that dev printed, then open Notes.

Read it through the API

curl http://localhost:9187/__first/api/v1/notes

You should see the same note in a list, with a cursor for the next page (null: there is none):

{"data":[{"id":5,"title":"Hello","body":null,"status":"published","publishedAt":"2026-11-09T04:26:14.000Z"}],"cursor":null}

Now try to create a note without signing in:

curl -X POST http://localhost:9187/__first/api/v1/notes \
	-H 'Content-Type: application/json' \
	--data '{"title":"From curl"}'

The access rule refuses it:

{"type":"about:blank","title":"Unauthenticated","status":401,"code":"unauthenticated","detail":"Sorry, you are not allowed to create posts as this user."}

Stop the site

npm run stop

Your notes stay in the local database for the next npm run dev.

What to commit

Commit first.config.ts and first/_generated/, which holds the migrations, the typed client, the editor types and openapi.json, the app’s API as an OpenAPI document. Keep first/dist/ and .first/ out of git. They hold the build output and the local site. The starter app’s .gitignore already does this.

Add a database

The notes are WordPress posts: that is the content half of First, and a new app starts with only that. When the app needs data of its own, such as orders, bookings or votes, add SQL tables:

npx first add db

It writes first/tables.ts, with two example tables joined by a reference and their access rules, typed client calls in tables.client.ts, and first/DATABASE.md, which explains migrations and the deploy check. It only creates files that are missing, so you can run it again. The next npm run build writes the SQL for the tables to first/_generated/migrations/.

Use a collection for what people write and publish in the WordPress editor. Use a table for rows your app filters, sorts, counts and joins: post meta has no real column types or foreign keys, and filtering and sorting on it is slow.

Next steps