Build your first app

Create an account, save a private note and summarise it with AI. Start with working application code you can change.

On this page

Before you start

Use Node.js 24+, npm and MariaDB. The starter uses Vue, DOM Studio and Fastify with the DB3 framework. Docker is optional. You do not need Scout or a copy of the framework repository.

An OpenAI API key is optional. Registration, login and private notes work without one. Each developer supplies their own server-side key to enable the AI example.

Create the app

The package is @db3.ai/create, not create-app. The command below is the intended public entry point. The packages are not published yet: use the preview instructions in the next section for now.

Once released, the creator makes a new directory, waits for your local database configuration, installs dependencies, applies committed migrations and starts development. It refuses an existing directory and never copies an AI key from your machine.

bash

npm create @db3.ai@latest my-app

Run the unpublished preview

Obtain the matching Create, App and Pure tarballs from a maintainer. Replace the three /path/to/ values with their absolute file paths. Run outside the framework repository. This is a temporary preview installation, not evidence of a public npm release.

The generated README is part of the app and covers database setup, configuration, testing and production boundaries. Follow it before starting the server.

bash

npm exec --yes --package=/path/to/db3.ai-create-0.1.0.tgz -- create-db3 my-app --no-install
cd my-app
npm install /path/to/db3.ai-pure-0.1.0.tgz /path/to/db3.ai-app-0.1.0.tgz

Use a local MariaDB database

On macOS with Homebrew, run brew install mariadb, then brew services start mariadb. Create a new database and an app-specific TCP account using the SQL in your generated README.

Set DB_HOST, DB_PORT, DB_DATABASE, DB_USER and DB_PASSWORD in .env. Keep this file out of Git. Remove an inherited DATABASE_URL unless you deliberately want it to override those settings. Never point this starter at an existing app database.

Or use Docker for MariaDB

After release, add -- --docker to the create command. This starts MariaDB in Docker while Node still runs locally. For a generated-only preview, set DB_PORT=33067 and a non-empty DB_PASSWORD in .env, then run docker compose up -d --wait db.

Use a local Docker engine. A remote context publishes the port on another computer, so the creator refuses remote endpoints. Standalone docker-compose installations are also recognised.

docker compose stop retains the database volume. Removing the volume deletes its data. Changing an environment password does not reset an existing database account.

Run it and save a note

After installing the preview packages and configuring MariaDB, run the commands below. Open http://localhost:5173, create an account and save a note. Reload: the note should still be there. Sign out and back in: your private notes should return.

The app uses a real Auth session in an HttpOnly cookie, and the Note model uses save() to persist data. The server assigns ownership; a browser cannot choose another account’s owner ID. A second account cannot read, delete or summarise your note.

bash

npm run db:migrate
npm run dev

Summarise a note with your own AI key

Add your own OPENAI_API_KEY to the generated app’s server .env, then restart. The key belongs to the developer operating the app. End users do not need to enter individual keys. Never expose it through VITE_ variables, Vue code or Git.

Click Summarise with AI on a saved note. Only that note is sent to OpenAI. The result is shown separately; it does not overwrite your original. The prompt and authorization live in server/ai/summariseNote.ts; the reusable client is imported from @db3.ai/app/ai.

Provider charges apply. The example caps input and output, disables automatic retries and uses a timeout. Its in-memory attempt limits are not a spending cap. Missing keys leave notes usable; provider failures show a safe error. Review AI output before using it.

bash

OPENAI_API_KEY=your-own-key
OPENAI_MODEL=gpt-4.1-mini

Build the next feature

Start with server/models/Note.ts and src/App.vue. Add a field, update HTTP validation and the UI, then run npm run db:make:migration -- add_note_field. Review the generated migration, run npm run db:migrate, and commit the migration with its schema snapshot.

For an optional field, use field.string({ required: false, maxLength: 160 }), not nullable: true. The generated README shows the full subtitle extension. The migration command runs type checking first so an invalid field option cannot silently produce a migration.

The starter keeps application code visible. DB3 owns Auth, ActiveRecord and the reusable AI client. Your app owns routes, authorization, prompts and product policy.

Test your app

Run the commands below from the generated app. npm test needs a dedicated test MariaDB account with CREATE/DROP permissions for db3_app_test_*; configure the TEST_DB_* variables as described in its README. Missing infrastructure fails instead of skipping.

The tests run real Auth, notes and committed migrations in disposable databases. Only OpenAI HTTP is simulated. They cover registration/login/logout, persistence, owner isolation, missing keys and provider failure without spending money or using your real API key.

bash

npm run check
npm run build
npm test

What this starter covers

The first slice is a landing page, password accounts, a private notebook and an optional AI summary. Google provider configuration is laid out, but a complete Google sign-in screen is still TODO. Setting a client ID alone does not add that flow.

Password-reset screens, email verification, organisations, billing, durable AI accounting, shared limits, app installation and a complete production deployment guide remain TODO. DOM Studio has its own licence. This example is not a complete production SaaS.