# Public addresses

Declare where each entry of a collection or Single is served, and read an entry's address with publicAddressOf.

A page's public address is where a visitor reaches it on your site: `/blog/hello` for a post, `/` for a homepage. You declare it once, and `publicAddressOf` answers it, so code that builds a canonical link, a sitemap entry or a redirect from that answer never disagrees with itself, and a type with no declared address gets none rather than a guess.

This is experimental. With the [SEO plugin](https://nextlyhq.com/docs/plugins/seo.md) installed, it decides where pages are listed and what they name as canonical: the sitemap lists each published page of a type at its declared address, and leaves out a type that declares none, and each page's canonical link is its declared address in its language. Without the plugin, nothing reads it unless you call it.

## Declaring an address

A collection or Single declared in code states its address with `publicAddress`:

```ts
import { defineCollection, defineSingle, text } from "nextly/config";

export const posts = defineCollection({
  slug: "posts",
  fields: [text({ name: "title" }), text({ name: "slug" })],
  publicAddress: "/blog/{slug}",
});

export const home = defineSingle({
  slug: "home",
  fields: [text({ name: "headline" })],
  publicAddress: "/",
});
```

The rules are on the [collection](https://nextlyhq.com/docs/configuration/collections.md#publicaddress) and [Single](https://nextlyhq.com/docs/configuration/singles.md#publicaddress) pages.

A collection whose entries are not all served under one pattern can also name a text field holding an entry's own address with [`publicAddressField`](https://nextlyhq.com/docs/configuration/collections.md#publicaddressfield) (experimental). An entry with a value there is served at it, and the rest at the template. `publicAddressOf` answers the entry's own address, so canonical links, sitemap entries and redirects follow it.

A type made in the Visual Schema Builder has no `publicAddress` of its own. A plugin can supply one through the `publicAddress.template` seam. It is judged by the same rules, and an address that breaks them counts as none.

For a type with neither, `publicAddressOf` answers that it has no address.

## Reading an address (`@experimental`)

Code that needs an entry's address asks `publicAddressOf`, from `nextly` or `@nextlyhq/plugin-sdk`:

```ts
import { publicAddressOf } from "nextly";

const post = { id: "1", slug: "hello" };

const address = await publicAddressOf(
  { kind: "collection", slug: "posts" },
  post
);
// { status: "resolved", path: "/blog/hello" }
```

| `status`        | Meaning                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------- |
| `"resolved"`    | The entry is served at `path`.                                                            |
| `"none"`        | The type has no public address.                                                           |
| `"unavailable"` | The type has one, but this entry has no value yet to fill it with, such as an empty slug. |

`typesWithoutAddress()` lists the site's collections and Singles that have no address yet. A plugin's own types and Nextly's system types are never listed.

## Keeping addresses unique

Nextly keeps no record of which page holds which address. Plugins that keep one, such as the SEO plugin, take part in keeping each address to one page: see [Unique public addresses](https://nextlyhq.com/docs/plugins/public-addresses.md).
