# defineApp / Application

> Documentation for Redweb 0.15.0. Install that exact version when following these examples.

Define pages, socket routes and application services together. Nothing listens until run(); one owner starts and stops the shared HTTP/WebSocket listener.

## Explain it like I’m five

One front door serves pages and ongoing socket conversations. The application prepares its staff before opening that door, then closes the door and sends the staff home in order.

## When should I use it?

Use it as the entry point for a multi-page site, a realtime UI, a routed socket backend, or their combination. Lower-level server classes remain available for custom ownership.

## Follow the example

This API pattern illustrates the named surface; it may require application-owned classes, credentials, or assets. Start from a complete recipe for a runnable application.

```js
import { defineApp } from 'redweb';
import { HomePage, DashboardPage } from './pages';
import { MatchRoute, ChatRoute } from './sockets';
import { GameSimulation } from './simulation';

const app = defineApp({
  pages: [HomePage, DashboardPage],
  sockets: [MatchRoute, ChatRoute],
  services: [GameSimulation],
  port: 8181,
});

await app.run();
```

1. Declare pages with decorators and socket routes with message-type handlers, then register their classes in one definition.
2. Acquire app-wide resources in service onInit(app, signal), not constructors. onInit can register Express endpoints through app.app before listening.
3. Await run to know startup succeeded; no separately stored HTTP server or second socket startup call is necessary. CommonJS entry points use an async function or handle the returned promise; top-level await requires a suitable ESM configuration.
4. For tests, use an ephemeral port, disable process signal ownership and await shutdown in cleanup. The generated applications ship real HTTP/socket and process tests.

## Options

- pages: decorated page classes (default [])
- sockets: SocketRoute classes (default [])
- services: application-wide classes with onInit(app, signal) and onShutdown() (default [])
- port: number (default 8181); use 0 for an ephemeral test port
- bind: string (default 0.0.0.0)
- httpServices: existing Express service descriptors; route-specific SocketService classes remain on socket routes
- startupTimeoutMs / shutdownTimeoutMs: total lifecycle budgets (default 5000 each)
- signals: install owned process signal handling when run begins (default true); embedded applications/tests can set false
- Existing live-page/HTTP options, including templateRoot, authentication, origins, server (Express app), development and ssl
- Static export remains exportStatic(); defineApp does not accept a static export flag

## Methods and members

### defineApp(options) / new Application(options)

Create a deferred definition. Registration arrays are copied; imports and definitions open no port or process handlers.

### run(): Promise<Application>

Initialize services in order and bind one HTTP/WS listener. Repeated calls share startup while running. A stopped application cannot restart.

### shutdown(): Promise<void>

Cancel pending startup and perform bounded, idempotent cleanup. Close HTTP/socket resources before releasing application services in reverse order. Preserve cleanup errors.

### options

Copied definition, available for defining independent test applications with port: 0 and signals: false. Captured objects and supplied Express apps are not deep-cloned.

### app / server / http / sockets / services

Runtime Express application, native listener, HTTP adapter, optional WebSocket server and service instances. HTTP members are null before startup; await run before use.

### revoke(principal): Promise<number>

Revoke matching live-page sessions; zero before live pages have been initialized.

### inspect(): DevelopmentSnapshot | null

Return opt-in live-page inspection metadata, or null when unavailable/disabled.

## What should I watch for?

This is lifecycle composition, not dependency injection or durable/distributed state. Services must cooperate with cancellation and release partially acquired resources. Deadlines cannot interrupt synchronous event-loop blocking. Shared page-class closure objects stay shared; use separate classes/rooms when isolation is required.