> ## Documentation Index
> Fetch the complete documentation index at: https://pulian.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HttpNext Pipeline

> Next.js plus Hile API controllers on one Koa server.

# HttpNext Pipeline

## Copy-Paste Example

```ts theme={null}
// src/services/http.boot.ts
import { defineService } from '@hile/core'
import HttpNext from '@hile/http-next'

export default defineService('http.next', async (shutdown) => {
  const app = new HttpNext({
    port: Number(process.env.HTTP_PORT ?? 3000),
    cwd: process.cwd(),
    publicPath: 'public',
  })
  const stop = await app.start()
  shutdown(stop)
  return app
})
```

## More Examples

Recommended layout:

```text theme={null}
src/
  app/              Next.js App Router pages
  controllers/      Hile API controllers, default prefix /-
  models/           Reusable business logic
  services/         *.boot.ts and app services
```

Use `loadModel()` from pages or controllers for domain logic. If a Next.js page uses runtime model data, mark the route dynamic:

```tsx theme={null}
export const dynamic = 'force-dynamic'
```

## Runtime And Lifecycle Notes

* `HttpNext` wraps an internal `Http` instance.
* It serves `publicPath`, then `.next/static`, then Hile controllers, then Next.js as the fallback handler.
* Development mode is determined by `process.env.NODE_ENV === 'development'`.
* Controller directory is `{cwd}/src/{controllerDirectory}` in development and `{cwd}/dist/{controllerDirectory}` in production.
* `specialControllers` load additional controller roots with their own prefixes.

## Anti-Patterns

* Putting API routes in Next.js when the app is intentionally using Hile controllers.
* Calling `loadService()` at module top level in Next.js files.
* Forgetting `cwd`; relative controller and Next artifact paths depend on it.

## Verification Checklist

* `HttpNext.start()` close function is registered with `shutdown`.
* Controllers live under the configured controller directory.
* API routes use the configured prefix, default `/-`.
* Next.js production build runs before `hile start` in production.