# Routes

> The core primitive in routeup is the route, a dotted name that maps to a stable HTTPS hostname.

A route is the stable name routeup gives a local service. Locally, routeup maps it to `https://<route>.localhost`.

## Valid names

Valid route names are DNS-style labels joined with dots:

```txt
example-app
api.example-app
docs.example-app
```

Invalid examples:

```txt
.example-app
example-app.
api..example-app
my_app
example-app.localhost
example-app.routeup.dev
```

Route names are lowercased. Each label may contain ASCII letters, digits, and hyphens, but not leading or trailing hyphens.

## Local hostnames

routeup appends `.localhost` for local use:

```txt
example-app      -> https://example-app.localhost
api.example-app  -> https://api.example-app.localhost
```

The `.localhost` suffix is not part of the route name.

## Public hostnames

Every public hostname is one label under the namespace granted by the server:

```txt
example-app      -> example-app
api.example-app  -> api-example-app
```

Dotted route names remain valid locally. When a dotted route is exposed, routeup
replaces dots with hyphens for the public label: `api.example-app` stays
`https://api.example-app.localhost` locally and requests public label
`api-example-app` automatically.

The server places that label under the granted namespace base:

```txt
no token       https://api-example-app.try.routeup.dev
root token     https://api-example-app.routeup.dev
namespace      https://api-example-app.team.routeup.dev
```

## Name resolution

`routeup serve` resolves the name in this order:

1. Positional argument, such as `routeup serve example-app`.
2. `ROUTEUP_NAME`.
3. `name` from `routeup.json` or the `package.json` `routeup` block.
4. The working-directory basename.

Every explicit positional name is literal. With config name `example-app`,
`routeup serve api` serves route `api`; use `routeup serve api.example-app` when
that exact dotted route is wanted.