Ninots

ninots is the official starter kit for the Nino ecosystem. It provides a production-ready project structure on top of Bun and TypeScript using published @ninots/* packages directly (no umbrella @ninots/framework in the consumer).

Nino focuses on developer experience inspired by Laravel and Next.js, while remaining its own framework and API design (not a compatibility layer for either).

Ecosystem Overview

• Organization: nino-ts
• Maintainer organization: pandowLABS
• Starter kit (this repository): nino-ts/ninots
• Packages: @ninots/* on npm + JSR (nino-ts/<name>), e.g. @ninots/foundation, @ninots/routing, @ninots/view

Requirements

Official support: Bun only.

Supported	Unsupported
Bun (runtime + package manager)	npm client, Node.js, yarn, pnpm

This starter is TypeScript + Bun: sources stay .ts / .tsx executed by Bun. Type-check uses tsc --noEmit — there is no “emit JS then run” DX, and we do not add app .js sources for that purpose.

• Optional: Docker Desktop for docker compose up (image still runs Bun)

Quickstart (local Bun)

# 1) Install published @ninots/* from npm
bun install

# 2) Copy env
cp .env.example .env

# 3) Dev server (hot reload)
bun run dev

# 4) Explore CLI
bun run nino --help

Hub developers can optionally override a package with bun link @ninots/<name> against a local packages/<name>/ clone.

Typed routes

In development (bun run dev / nino serve with APP_DEBUG=true), Ninots watches routes/ and app/Modules/ and rebuilds types/routes.d.ts automatically (debounce + same emitter as routes:compile).

For CI and production builds, keep the explicit compile:

bun run nino routes:compile   # writes types/routes.d.ts (CI / manual)
bun run verify:route-types    # fail-fixture checks

Named routes use .name("recurso.ação"); typed URLs via route(name, params?).

Three “hot” mechanisms (do not confuse them)

Mechanism	What it updates	How you get it
bun --hot (server)	Soft-reloads the server process / handlers	bun run dev → bun --hot ./nino serve
Bun fullstack HMR (client)	Updates browser modules without a full page reload (import.meta.hot)	Bun.serve({ development: true, routes: { … HTML imports } }) — try /hmr-demo
Routes auto-hook	Rebuilds types/routes.d.ts (typed route())	Watch → debounce → cold nino routes:compile (compileArtifact; see ninots#47)

Editing resources/hmr-demo/hmr-demo.client.ts exercises client HMR. Editing routes/web.ts exercises the auto-hook — not the browser HMR path. HTML demo routes are additive; the typed Router stays the source of truth for named routes.

Docker (compose)

Default stack: app + SQLite volume (no extra DB container).

cp .env.example .env
docker compose up --build -d
# smoke: curl -sf http://localhost:3000/  → HTTP 200
docker compose down

Optional Postgres profile:

docker compose --profile postgres up --build -d
# app-postgres uses DB_CONNECTION=postgres → host `postgres`
docker compose --profile postgres down

Entry command: ./nino serve --port 3000 (wrapper → bootstrap/cli.ts).

Available Commands

Command	Description
bun run dev	nino serve with hot reload; auto-rebuilds types/routes.d.ts in development
bun run start	Production-style serve
bun run build	Compiled binary (ninots)
bun run nino --help	CLI help
bun test	All tests
bun run type-check	tsc --noEmit
bun run lint	Biome check
docker compose up --build	Containerized app (SQLite volume)

Architecture

Boot flow

nino (wrapper → bootstrap/cli.ts) is the CLI entrypoint. The serve command:

1. Calls bootstrap() from bootstrap/app.ts
2. Creates container + application instance
3. Registers providers from bootstrap/providers.ts
4. Boots the app
5. Starts Bun.serve(...) with generated options
6. In development, starts startRoutesAutoHook (watch → debounce → cold nino routes:compile subprocess → types/routes.d.ts)

Routing

Fluent registration under routes/web.ts and routes/api.ts (Laravel-like). File-based loadRoutes exists in @ninots/routing but is not wired in this starter. Dev auto-hook rebuilds types/routes.d.ts when those files change; CI still runs nino routes:compile explicitly.

Layout

app/              # Http, Models, Providers, …
bootstrap/        # app.ts, cli.ts, providers
config/           # runtime configuration
routes/           # web, api, console
resources/views/  # TSX views (@ninots/view)
resources/hmr-demo/ # Bun HTML-import client HMR demo (`/hmr-demo`)
database/         # migrations, seeders
types/            # routes.d.ts (compile artifact)
nino              # CLI wrapper → bootstrap/cli.ts
Dockerfile        # Bun official image
compose.yaml      # SQLite default; postgres profile

Path alias: @/* → project root.

Development and Testing

bun test
bun run type-check
bun run verify:route-types
bun run lint

Feature HTTP helpers live in tests/support/ (createTestApp, get/post, asserts). See tests/support/README.md.

CEO gates (contributions)

• Zero any (explicit or implicit)
• Zero suppressions (biome-ignore, @ts-ignore, @ts-expect-error, eslint-disable)
• Zero new runtime deps outside @ninots/*
• See AGENTS.md for agent-oriented notes

Maintainers

• João Vitor de Jesus Oliveira (site, GitHub)
• Victor Geruso (site, GitHub)

Contributing

Issues and pull requests are welcome in the nino-ts organization.

Same-repo PRs (CI gate)

Open pull requests from a branch on nino-ts/ninots, not from a personal fork.

git remote add upstream https://github.com/nino-ts/ninots.git   # if needed
git push -u upstream HEAD:patch/your-branch
# then open the PR head = nino-ts/ninots:patch/your-branch → base main

Cross-fork PRs may not receive GitHub Actions check-runs (see #40). Use regular merge only (never squash or rebase).

License

Nino is open-source software released under the MIT License.