Quickstart

Create a Hile project and understand the first boot file, controller, and lifecycle cleanup.

Quickstart

Complete Example

npx create-hile create orders-api
cd orders-api
pnpm install
pnpm run dev

Default HTTP controller:

// src/controllers/index.controller.ts
import { defineController } from '@hile/http'

export default defineController('GET', async () => {
  return { ok: true }
})

Default HTTP boot:

// src/services/index.boot.ts
import { defineService } from '@hile/core'
import { Http } from '@hile/http'

export default defineService('http', async (shutdown) => {
  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
  await http.load(new URL('../controllers', import.meta.url).pathname)
  const close = await http.listen()
  shutdown(close)
  return http
})

Use When

Use create-hile when starting a new Hile application or workspace.

More Examples

Template choices:

default          HTTP API with @hile/http
next             Next.js + Hile controllers on one port
micro-http       Microservice plus HTTP endpoint
micro            Pure microservice
micro-http-next  Next.js + microservice + HTTP
rsc-host         Single public Next host for internal RSC plugins
rsc-plugin       Independently built RSC plugin service without HTTP
monorepo         Lerna + pnpm workspace

Generated default HTTP shape:

src/
  controllers/
    index.controller.ts
  services/
    index.boot.ts

Runtime And Lifecycle Notes

• Templates use _env, _env.prod, and _gitignore; creation renames them to dotfiles.
• The CLI prompts for a template and optional dependency installation.
• Generated templates use pnpm consistently; install pnpm before running create-hile without --skip-install.

Anti-Patterns

• Leaving template package versions stale after publishing new Hile packages.
• Shipping template READMEs copied from unrelated projects.
• Starting production without running the build command required by the selected template.