Install the framework

Install one runtime package, then build a small HTTP app. Add a database and other services when your feature needs them.

On this page

Source-backed Markdown

Want a working app shell?

The @db3.ai/create preview generates a Vue/DOM Studio app with password login, private notes and optional AI summaries using your own server-side API key. Start there for a complete first feature. This page covers installing the runtime for a smaller HTTP app or script.

Create the notes and AI starter

Before you start

Use Node.js 24 or newer and npm for these walkthroughs. Start in a new directory, outside the framework repository. You do not need Scout, Vue, a database or cloud credentials for the first HTTP app.

The runtime package is @db3.ai/app. Its matching @db3.ai/pure dependency contains portable helpers. Fastify is optional: install it for this HTTP example, not for a script that only uses Storage.

Publication status

The framework and creator are not published to npm yet. The intended released install command is shown below, but it will not work until the first release. Use matching package tarballs supplied by a maintainer for now.

bash

npm install @db3.ai/app

Install the current preview

Obtain the matching App and Pure tarballs from a framework maintainer. Replace both /path/to/ values below with those files. Install them together because the unreleased App package depends on the matching Pure version.

Nothing in this command publishes your application. Marking it private also protects against accidentally running npm publish from the app directory.

bash

mkdir my-db3-app
cd my-db3-app
npm init -y
npm pkg set type=module
npm pkg set private=true --json
npm install /path/to/db3.ai-pure-0.1.0.tgz /path/to/db3.ai-app-0.1.0.tgz

Add the development tools

tsx runs the copied TypeScript examples, TypeScript checks them, and Vitest runs your application tests. Fastify owns the HTTP listener; App owns framework services.

Create and run your first app

bash

npm install fastify@^5
npm install --save-dev tsx@^4 typescript@^6 @types/node@^24 vitest@^4

Configure SQL when a guide needs it

Auth, ActiveRecord, Media, database-backed Queue and Scheduler need MariaDB/MySQL. Their isolated labs require a dedicated local test account allowed to create and drop databases prefixed db3_app_test_. Do not use production credentials. Storage and the first HTTP app do not need SQL.

Save the configuration below as .env in your new app directory, replacing the user and password. Keep .env out of Git. DATABASE_URL, if set in your shell, takes precedence; unset it unless it deliberately points at your test server.

Each lab creates a unique database and removes it in finally. A forcibly killed process may leave a test database or temporary directory to inspect. The lab’s Database.install() is not your production migration workflow.

bash

DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=your_test_user
DB_PASSWORD=your_test_password
DB_DATABASE=db3_app_test
DB_TEST_DATABASE_PREFIX=db3_app_test

When installation fails

An npm 404 for @db3.ai/app is expected before publication. For the preview, check that both tarball paths exist and their versions match. Do not substitute an unrelated npm package with a similar name.

If SQL reports connection refused, check its host and port. Access denied usually means credentials or grants; a socket-only account may not allow TCP login. Database creation needs additional test-account privileges beyond reading an existing database.

If port 3000 is occupied, choose another PORT when starting the HTTP example. None of the guides requires a global TypeScript or framework CLI installation.

For framework maintainers

These commands are for a framework checkout only. They compile and pack the two public-shaped packages and verify a fresh consumer. They do not publish. Share the two resulting tarballs with preview users, who start at Install the current preview above.

bash

npm run framework:package
npm pack ./dist/framework-packages/pure --pack-destination ./dist/framework-packages
npm pack ./dist/framework-packages/app --pack-destination ./dist/framework-packages
npm run framework:package:test

What is working, and what comes next

The minimal HTTP guide below has a real HTTP test and uses installed package artifacts. The separate Notes + AI starter adds a generated Vue shell, authentication and migrations. Public npm installation remains a release gate, not an already available command.