Installation

Harpia is designed to be flexible. You can either integrate the core library into an existing project or scaffold a complete, production-ready application using our CLI.

Bun Required

Harpia is built for the Bun runtime. Ensure you have Bun v1.2+ installed.

Choose your path

Depending on your project needs, you can start with just the essentials or the full powerhouse.

Core

Best for minimalists or adding Harpia to an existing Bun project.

bun add @harpiats/core

App

Best for new projects that need Auth, Database, and a solid structure.

bun create harpia-app my-api

CLI Flags

The create-harpia-app command supports flags for fully non-interactive setup — useful for CI pipelines and scripts.

Application Mode

Flag	Shorthand	Description
`--api`	`-a`	Scaffold an API-only project
`--fullstack`	`-f`	Scaffold a Fullstack project

Database

Flag	Shorthand	Description
`--postgresql` / `--postgres`	`-p`	Use PostgreSQL
`--mysql`	`-m`	Use MySQL / MariaDB
`--sqlite`	`-s`	Use SQLite (via LibSQL)

Fullstack Options

These flags are only applied when --fullstack is used.

Flag	Shorthand	Description
`--tailwind`	`-t`	Include Tailwind CSS
`--alpine`	`-l`	Include Alpine.js
`--htmx`	`-h`	Include HTMX

Non-Interactive Example

# Scaffold an API project with SQLite in one shot
bun create harpia-app my-project --api --sqlite

# Scaffold a Fullstack project with PostgreSQL, Tailwind and HTMX
bun create harpia-app my-app --fullstack --postgresql --tailwind --htmx

Manual Setup (Core)

If you chose the Core path, you’ll need to initialize your server manually. Harpia Core is lightweight and gives you full control over the entry point.

Start the server

Create an index.ts file and add the following code to spin up your first Harpia instance:

import harpia from "@harpiats/core";

const app = harpia();

app.listen(
  {
    port: 3000,
    development: true,
    reusePort: true,
    hostname: "localhost",
  },
  () => console.log("Server is running at http://localhost:3000/"),
);