Holo

Appearance

Installation ​

The primary installation path is the package manager's create flow. It creates the project, asks the setup questions up front, writes the hidden framework glue once, and leaves the user with configurable server-side config files plus Holo-JS-owned server directories.

Requirements ​

  • Node 22.12 or newer
  • a modern package manager (npm, pnpm, yarn, or bun)
  • one of: Nuxt, Next.js, or SvelteKit
  • SQLite, Postgres, or MySQL

The scaffold installs one concrete database driver package matching the selected database: @holo-js/db-sqlite, @holo-js/db-postgres, or @holo-js/db-mysql. Install additional concrete drivers explicitly when an application uses multiple database engines.

Create a project interactively ​

bash
npm create holo-js@latest my-app
bash
pnpm create holo-js@latest my-app
bash
yarn create holo-js my-app
bash
bun create holo-js my-app
  • storage default disk: local or public
  • optional packages: validation, forms, security, notifications, mail, storage, events, queue, cache, auth, authorization, broadcast, realtime, or none

Create a project non-interactively ​

bash
npm create holo-js@latest my-app -- \
  --framework next \
  --database sqlite \
  --package-manager npm \
  --storage-default-disk public \
  --package forms,validation,mail
bash
pnpm create holo-js@latest my-app -- \
  --framework next \
  --database sqlite \
  --package-manager pnpm \
  --storage-default-disk public \
  --package forms,validation,mail
bash
yarn create holo-js my-app \
  --framework next \
  --database sqlite \
  --package-manager yarn \
  --storage-default-disk public \
  --package forms,validation,mail
bash
bun create holo-js my-app \
  --framework next \
  --database sqlite \
  --package-manager bun \
  --storage-default-disk public \
  --package forms,validation,mail

Use the non-interactive flags for CI, templates, or internal automation.

validation, forms, security, notifications, mail, storage, events, queue, cache, auth, authorization, broadcast, and realtime are optional packages. Add them during scaffolding only if the app needs them.

Example optional package sets include --package forms,validation,notifications, --package forms,validation,mail, --package forms,validation,security, and --package authorization.

Authorization can also be installed after scaffolding:

bash
npx holo install authorization
bash
pnpm dlx holo install authorization
bash
yarn dlx holo install authorization
bash
bunx holo install authorization

Broadcast setup is installed after scaffolding:

bash
npx holo install broadcast
bash
pnpm dlx holo install broadcast
bash
yarn dlx holo install broadcast
bash
bunx holo install broadcast

Realtime setup can also be installed after scaffolding:

bash
npx holo install realtime
bash
pnpm dlx holo install realtime
bash
yarn dlx holo install realtime
bash
bunx holo install realtime

Cache setup can also be installed after scaffolding:

bash
npx holo install cache
bash
pnpm dlx holo install cache
bash
yarn dlx holo install cache
bash
bunx holo install cache

Media setup can also be installed after scaffolding:

bash
npx holo install media
bash
pnpm dlx holo install media
bash
yarn dlx holo install media
bash
bunx holo install media

What the scaffold writes ​

The generated project contains:

  • framework-owned files for the selected host framework
  • config/*.ts for Holo-JS config
  • layered env support with .env and .env.example
  • canonical Holo-JS directories such as server/models, server/db, server/commands, server/jobs, server/events, and server/listeners
  • first-party queue scaffold including config/queue.ts with sync as the default driver
  • auth scaffold including config/auth.ts, config/session.ts, user/session migrations, and default current-auth support at /api/auth/user when auth is selected
  • machine-owned generated output under .holo-js/generated
  • framework lifecycle scripts such as dev and build
  • for SvelteKit, svelte.config.js is wrapped with withHoloSvelteKit(...) so Holo can install the generated hook bridge without asking users to edit hook paths by hand

The auth scaffold does not generate application flows such as /login, /register, /logout, password reset, email verification, admin pages, or route-protection middleware. Those routes depend on the app's forms, redirects, and page structure. Add them in your application code and point useAuth() at a custom current-auth endpoint if you choose not to use /api/auth/user.

The generated framework glue is not the user-edited setup surface. After scaffolding, the normal places to work are:

  • config/*.ts
  • .env and environment-specific env files
  • server/models
  • server/db
  • server/commands
  • server/jobs
  • server/events
  • server/listeners

SvelteKit users normally leave the withHoloSvelteKit(...) wrapper in place and edit the config object inside it. holo prepare preserves unrelated user configuration and owns the generated server and universal hook entrypoints.

First commands ​

After scaffolding, install dependencies and start the dev server using the package manager you selected:

bash
cd my-app
npm install
npm run dev
bash
cd my-app
pnpm install
pnpm dev
bash
cd my-app
yarn install
yarn dev
bash
cd my-app
bun install
bun run dev

npm run dev (or the equivalent for your package manager) already runs discovery first, refreshes .holo-js/generated, watches relevant files, and then starts Nuxt, Next.js, or SvelteKit. Run npx holo prepare (or the equivalent exec wrapper for your package manager) only when you want to regenerate discovery artifacts without starting the dev server.

Running Holo-JS commands inside a project ​

Use normal package scripts for framework lifecycle commands:

bash
npm run dev
npm run build
npm run start
bash
pnpm dev
pnpm build
pnpm start
bash
yarn dev
yarn build
yarn start
bash
bun run dev
bun run build
bun run start

The start script runs holo start, which starts the production server with Holo runtime preloads before handing off to Nuxt, Next.js, or SvelteKit.

Use your package manager's exec wrapper for direct Holo-JS CLI commands:

bash
npx holo make:model User
npx holo migrate
npx holo seed
bash
pnpm dlx holo make:model User
pnpm dlx holo migrate
pnpm dlx holo seed
bash
yarn dlx holo make:model User
yarn dlx holo migrate
yarn dlx holo seed
bash
bunx holo make:model User
bunx holo migrate
bunx holo seed

Use holo agents:install when you want Holo-JS documentation-search skills for AI coding agents.

Global install (optional) ​

If you prefer running holo directly from your terminal:

bash
npm install -g @holo-js/cli
holo list
holo make:model User
bash
pnpm add -g @holo-js/cli
holo list
holo make:model User
bash
yarn global add @holo-js/cli
holo list
holo make:model User
bash
bun add -g @holo-js/cli
holo list
holo make:model User

When using a global install, holo is expected to be on your shell PATH.

holo ... by itself is not expected to be on your global shell path unless you install it globally.

Host framework ownership ​

Holo-JS does not replace the host framework. The selected framework still owns:

  • SSR
  • routing
  • page rendering
  • hydration
  • framework build output

Holo-JS owns:

  • config loading
  • layered env resolution
  • database and ORM
  • storage and media
  • CLI workflows
  • generated discovery registries
  • backend flexibility across database drivers, storage drivers, and deployment targets

Security defaults ​

  • keep secrets in env files, never in client code
  • keep .env.example limited to keys and placeholders
  • keep .holo-js/generated gitignored
  • do not move secret-bearing config into browser-visible runtime paths

Continue ​

Holo owns backend runtime concerns. The host framework owns SSR and routing.

Documentation site rebuilt with markdown-first editing and VitePress.