# Custom pages and API routes reference

Copy as Markdown[View as Markdown](/docs/development/customization/custom-pages-and-api-routes/reference.md)

***

## Route prefix[​](#route-prefix "Direct link to Route prefix")

Custom pages and API routes are served under `/custom` by default.

Use `pages.prefix` to serve them somewhere else.

eventcatalog.config.js

```
export default {
  pages: {
    prefix: 'internal/tools',
  },
};
```

With this configuration:

| File                    | Route                          |
| ----------------------- | ------------------------------ |
| `pages/reports.astro`   | `/internal/tools/reports`      |
| `pages/api/services.ts` | `/internal/tools/api/services` |

The prefix must use URL-safe characters: letters, numbers, `-`, and `_`, optionally separated with `/`.

The prefix cannot be empty.

Some top-level routes are reserved by EventCatalog. If a configured prefix conflicts with a reserved route, EventCatalog will ask you to choose a different prefix.

## Routable files[​](#routable-files "Direct link to Routable files")

Code files in the top-level `pages` directory are treated as custom routes.

| Extension | Route type |
| --------- | ---------- |
| `.astro`  | Page       |
| `.ts`     | Endpoint   |
| `.js`     | Endpoint   |
| `.mjs`    | Endpoint   |

Other files in `pages`, such as images, are copied as static assets. For example, `pages/diagram.png` can be referenced from `/generated/pages/diagram.png`.

## Route patterns[​](#route-patterns "Direct link to Route patterns")

| File                         | Default route            |
| ---------------------------- | ------------------------ |
| `pages/reports.astro`        | `/custom/reports`        |
| `pages/reports/index.astro`  | `/custom/reports`        |
| `pages/reports/[id].astro`   | `/custom/reports/[id]`   |
| `pages/docs/[...slug].astro` | `/custom/docs/[...slug]` |
| `pages/api/teams.ts`         | `/custom/api/teams`      |
| `pages/data.json.ts`         | `/custom/data.json`      |

## Ignored files and folders[​](#ignored-files-and-folders "Direct link to Ignored files and folders")

Files or folders that start with `_` are not treated as routes.

Use this for partials, helpers, and colocated components.

| File                           | Result            |
| ------------------------------ | ----------------- |
| `pages/_partial.astro`         | Ignored           |
| `pages/_components/Card.astro` | Ignored           |
| `pages/reports/_helpers.ts`    | Ignored           |
| `pages/reports/index.astro`    | `/custom/reports` |

## Homepage exception[​](#homepage-exception "Direct link to Homepage exception")

`pages/homepage.astro` is rendered as the catalog homepage at `/`.

It is not served as `/custom/homepage`.

## Server mode[​](#server-mode "Direct link to Server mode")

Custom pages can be used in static or server output.

Custom API routes require server mode for production builds.

eventcatalog.config.js

```
export default {
  output: 'server',
};
```

If EventCatalog finds API routes in `pages/api` during a static build, the build fails and asks you to enable server mode or remove the `pages/api` directory.

## Import aliases[​](#import-aliases "Direct link to Import aliases")

Use these aliases in custom pages.

| Alias                           | Description                                                                       |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `@catalog/layouts/Layout.astro` | Stable EventCatalog layout shell for custom pages.                                |
| `@catalog/utils`                | Stable catalog data helpers such as `getServices`, `getDomains`, and `getEvents`. |
| `@catalog/components/*`         | Components from your catalog's top-level `components` directory.                  |

## `@catalog/utils`[​](#catalogutils "Direct link to catalogutils")

Use `@catalog/utils` to read catalog resources from custom pages and API routes.

pages/reports.astro

```
---
import { getServices, getDomains } from '@catalog/utils';

const services = await getServices({ getAllVersions: false });
const domains = await getDomains({ getAllVersions: false });
---
```

Getter functions return hydrated, cached collection entries. Pass `{ getAllVersions: false }` when you only want the latest version of each resource.

| Helper                                        | Returns                                                            |
| --------------------------------------------- | ------------------------------------------------------------------ |
| `getDomains`                                  | Domains                                                            |
| `getServices`                                 | Services                                                           |
| `getSystems`                                  | Systems                                                            |
| `getEvents`                                   | Events                                                             |
| `getCommands`                                 | Commands                                                           |
| `getQueries`                                  | Queries                                                            |
| `getFlows`                                    | Flows                                                              |
| `getChannels`                                 | Channels                                                           |
| `getEntities`                                 | Entities                                                           |
| `getAgents`                                   | Agents                                                             |
| `getContainers`                               | Containers                                                         |
| `getDataProducts`                             | Data products                                                      |
| `getAdrs`                                     | Architecture decision records                                      |
| `getTeams`                                    | Teams                                                              |
| `getUsers`                                    | Users                                                              |
| `getItemsFromCollectionByIdAndSemverOrLatest` | A specific version, semver range, or latest item from a collection |