@podosoft/podokit
v1.8.1
Published
An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.
Maintainers
Readme
@podosoft/podokit
PodoKit is an opinionated Bun 1.4.4 full-stack starter and CLI. It generates an
Elysia API, a SvelteKit web application, selectable PostgreSQL/SQLite 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.
Choose infrastructure
fullstack is the default template. todo adds a working CRUD example; base
is a minimal workspace with placeholder scripts. For a small working app, use
fullstack or todo with local providers rather than choosing base just to
avoid external infrastructure.
| Capability | Default | Local alternative |
| --- | --- | --- |
| Database | postgres — PostgreSQL | sqlite — database file |
| Cache | redis | memory — in-process cache |
| Object storage | s3 — AWS S3 or S3-compatible storage | local — local files |
| Events | redis | memory — in-process events |
| Jobs | bullmq — Redis queue and separate worker | local — database-backed embedded worker |
A simple program, prototype, desktop app, or single-process service can use SQLite, memory cache, and local files without PostgreSQL, Redis, or S3. Providers can be mixed. Local providers require one API process.
Only the database is selected during creation with --database postgres|sqlite.
Other capabilities use provider set after creation; there are no --cache or
--storage creation flags. Choosing SQLite alone leaves the other defaults
unchanged. Creation records selections, while applying a provider or adding a
feature installs the necessary optional implementation modules.
Quick start
Default server setup
npx @podosoft/podokit create my-app
# or: bunx --bun @podosoft/podokit create my-app
cd my-app
bun install
cp .env.example .env
npx @podosoft/podokit dev watchOpen 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 or SQLite persistence:

Small app with local providers
bunx --bun @podosoft/podokit create podokit --template todo --database sqlite --yes
cd podokit
bunx --bun @podosoft/podokit provider set cache memory --apply
bunx --bun @podosoft/podokit provider set object-storage local --apply
bunx --bun @podosoft/podokit provider set events memory --apply
bunx --bun @podosoft/podokit provider set jobs local --apply
bun install
cp .env.example .env
bun run --cwd apps/api migrate:allRun bun run --cwd apps/api dev and bun run --cwd apps/web dev in separate
terminals and open http://localhost:5001. This host-process setup requires no
Docker. SQLite and local files default to ./data/podokit.sqlite and
./data/files, relative to the API working directory. Memory state disappears
on restart; files and the database-backed local jobs persist.
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 provider list | Show active database, cache, object storage, event, and job providers. |
| podo provider set <capability> <provider> [--apply] | Preview or apply one provider change. |
| podo status | Show the PodoKit version, modules, ownership tiers, and local edits. |
| podo diff [path...] | List edited or deleted managed files, or show a file's diff against its template. |
| 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 restore <path...> | Rewrite managed files from the template; an ejected file becomes managed again. |
| podo dev <action> | Manage the generated development containers. |
| podo deploy <action> | Plan, apply, verify, or roll back an immutable Kubernetes or Docker Compose release. |
podo create <name> [options]
Options:
--template <name> fullstack (default), todo, or base
--dir <path> Target directory (default: ./<name>)
--database <name> postgres (default) or sqlite
--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 --applyModules 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.
Runtime providers
Inspect active selections and available alternatives with podo provider list.
podo provider set is a dry run by default and installs the selected
implementation module on --apply. Configure providers before adding features:
file-upload uses local storage when selected, and job-progress can use local
jobs and memory events. Changes append settings to .env.example; merge them
into an existing .env manually. Switching changes code and configuration only;
it never migrates or deletes data.
S3's development settings use Silo with STORAGE_PROVIDER=minio; use
STORAGE_PROVIDER=aws for AWS S3. Local files use LOCAL_STORAGE_PATH.
See the runtime provider guide before switching an existing project. For the complete creation sequence, see Getting Started.
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.4. 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/ # provider-aware external 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.4The 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.4-alpine.
