@podosoft/podokit

PodoKit is an opinionated Bun 1.4.0 full-stack starter and CLI. It generates an Elysia API, a SvelteKit web application, PostgreSQL integration through native Bun.SQL, Tailwind CSS v4, shadcn-svelte, Docker, and k3s assets.

The CLI itself remains Node-compatible, so either npx or bunx can create and maintain projects. Generated PodoKit v1 applications are Bun-only.

Quick start

npx @podosoft/podokit create my-app
# or: bunx @podosoft/podokit create my-app

cd my-app
bun install
cp .env.example .env
npx @podosoft/podokit dev watch

Open http://my-app.localhost. The first project starts a user-level Traefik gateway on loopback port 80; later projects reuse it and route by hostname. Stop the project with podo dev down.

The todo template generates a working SvelteKit UI, Elysia CRUD API, and PostgreSQL persistence:

Commands

| Command | Purpose | | --- | --- | | podo create <name> | Create a Bun project from fullstack, todo, or base. | | podo add <module> | Add a composable feature module. | | podo remove <module> | Remove a module conservatively. | | podo status | Show the PodoKit version, modules, ownership tiers, and local edits. | | podo diff | List edited or deleted managed files. | | podo doctor | Check Bun and framework versions. | | podo locale <command> | Manage JSON locales. | | podo update [--apply] | Preview or apply managed template and module updates. | | podo eject <path...> | Transfer managed files to application ownership. | | podo dev <action> | Manage the generated development containers. | | podo deploy <action> | Plan, apply, verify, or roll back an immutable Helm release. |

podo create <name> [options]

Options:
  --template <name>  fullstack (default), todo, or base
  --dir <path>       Target directory (default: ./<name>)
  --no-ai            Omit generated AI-agent guidance
  -y, --yes          Accept defaults without prompts
  -h, --help         Show help

--runtime bun remains an optional explicit selection. Node runtime values, --pm, and podo runtime set are not part of PodoKit v1. Version 1 projects deliberately use Bun-specific APIs on the request and data paths.

Modules and updates

podo add auth
bun install
bun run --cwd apps/api migrate:all

podo status
podo update
podo update --apply

Modules overlay files, merge dependencies and environment examples, then wire Elysia plugins into apps/api/src/app.ts. Generated projects record their assembly in .podokit/, allowing clean managed files to update and edited files to be three-way merged. Application-owned routes, components, and ejected files remain untouched.

See the module guide and updating guide.

Compatibility boundary

PodoKit v1 does not convert projects generated by PodoKit 0.x. Existing projects must pin @podosoft/[email protected] for maintenance. Start a new v1 project when adopting the Bun and Elysia architecture.

The generated application runtime, builds, migrations, and unit tests all use Bun 1.4.0. Playwright remains a Node-based test-tool exception because its officially supported runtime is Node; bunx playwright respects the package's Node shebang.

Generated architecture

my-app/
├── apps/
│   ├── api/        # Bun + Elysia + native Bun.SQL
│   └── web/        # SvelteKit + Tailwind CSS v4 + shadcn-svelte
├── infra/
│   ├── docker/     # PostgreSQL, Redis, and optional services
│   └── k3s/        # deployments, services, ingress, and examples
├── tests/          # Playwright API and browser tests
├── .podokit/       # assembly and managed-file metadata
└── package.json    # Bun workspace pinned to Bun 1.4.0

The API provides typed Elysia validation, a stable error envelope, liveness and readiness endpoints, merged OpenAPI documentation, and an executable route contract check. Production API and worker images use oven/bun:1.4.0-alpine.

License

Apache-2.0