create-hile

Scaffold Hile applications and monorepos from maintained templates.

create-hile

Scaffold Hile applications and monorepos from maintained templates.

Choose This Package When

User asks for	Use	Also read
Scaffold a new project	create-hile	packages/create-hile.md, recipes/new-project-scaffold.md

Use When

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

Do Not Use When

• Do not use generated templates as the final architecture for complex apps without introducing models, services, and context boundaries.
• Do not trust stale template README files if they mention unrelated application domains; regenerate or rewrite them from current template files.

Install

Usually no install is needed:

npx create-hile create my-app

Imports

The CLI entrypoint exports a create command. Application code does not import create-hile.

Copy-Paste Example

Create a project:

npx create-hile create my-app
cd my-app
pnpm install
pnpm run dev

Skip dependency install:

npx create-hile create my-app --skip-install

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
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.
• The package manager preference is pnpm, then yarn, then npm.

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.

Verification Checklist

• New project has "type": "module".
• Dev script runs hile start --dev.
• Production script runs hile start after build.
• Boot files default-export defineService(...).

Related Recipes

New Project Scaffold

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
})

Package-Local AI Guide

This package also ships AI.md in npm so agents can read accurate examples after installation.