How a site's addresses route — pages, features and 404s

Every URL on a hosted site is answered by one of four things: a built-in screen, a switched-on feature, a stored page, or nothing (a 404). Get the owner of the URL right before changing anything.

This page is about who owns an address. To build the page itself, see Build a website page; for a shop of your own design, Catalog pages from your products; for a form's link, Shared form from a collection. The site record's fields are in Sites, and page shapes in Pages and rendering.

The model in plain words

• A feature that's on owns its address. Blog on means /blog shows the built-in blog. No page is needed.
• Choosing a page for a feature moves the feature to that page's address and makes that page its template. The page's first screen is drawn above the feature and its second screen below. The old default address is freed for a normal page.
• A feature that's off gives the address back to normal pages. If no page has that address either, it's a 404. That 404 is correct.
• A page answers at /<slug> and at /<name>, ignoring case. The first URL segment decides; the rest is ignored for ordinary pages.

Forms, Unsubscribe and a few others bend these rules. They are listed under Exceptions.

Worked example: Blog

Tested on a local site. "Page blog" means a page record named blog; news stands for any other page.

The live example: Storefront

On PhaZZer's local site, data.features is ["e-commerce"] (e-commerce is the old name for Storefront):

• /store renders the built-in catalog (200). There is no page named store; the catalog is drawn inside the site's account-layout page.
• PhaZZer's own products and product pages are separate addresses, /products and /product. They render as themselves (200). The built-in store does not touch them.
• Use my own page in Site Features opens a page picker. Picking products writes { "feature": "storefront", "enabled": true, "page": "products" }. Tested: /store became a 404, /products rendered the built-in catalog inside the products page, /products/checkout was the store's checkout, and /store/checkout became a 404. The top-level /checkout stayed at 200.

The store's own addresses hang off its page: /<store>/<product slug> is a product, /<store>/checkout, /<store>/checkout/success and /<store>/order/<id>. A product slug that doesn't exist falls back to the catalog with a 200, not a 404. Categories and search are query parameters on the catalog (?categories=, ?tags=, ?keyword=, ?sort=).

Ask first

• Which URL, exactly, and from where? The full address, including the host and the query string. A link from an email: which email (form invitation, booking confirmation, invoice, gift card).
• Which site? An org can have several. Engine emails use the org's default site (step 1).
• What should be at that address? The built-in feature, their own page, or nothing. Never guess this: moving a feature changes which page a live URL shows.
• For a feature: the default address, or their own page? If their own page, which one. Its screens will wrap the feature and its own content will not show there as a page.

How a request is answered

For a request to <host>/<path>, the site checks these in order. The first match answers.

1. The site, from the host. The host is looked up among the platform's domain records (www. is stripped). The platform host is <site>-<org>.site.appmint.app, set as the site's data.hostName when the site is made. A custom domain is data.domain. Locally it's <site>-<org>.localhost:3200. An unknown host falls back to the org's site flagged data.isDefault. No site at all: a plain 404. (appengine site.service.ts getSite 88, getSiteByDomainName 467; base-app lib/get-page-data.ts 149)
2. A fixed route. /login, /account, /checkout, /api/… and the others in Routes that are not features. These are their own Next.js routes, so a stored page with the same name never shows.
3. /<name>.html is redirected (301) to /<name>; /index.html goes to /. (base-app src/middleware.ts)
4. A static prefix. A first segment that starts with _next, assets, favicon.ico, robots.txt, sitemap, site.webmanifest or tt renders a blank page with a 200. So /sitemap-page, /assets-guide and /ttravel can never be pages. (base-app lib-client/helpers.ts 3, [[...slug]]/page.tsx 256)
5. The stored page is looked up by the first segment: a page on this site whose slug or name matches, ignoring case, or whose id matches. / and /index look up site.data.homePage instead. With publishedPagesOnly: true, only published copies count. (appengine site.service.ts getPage 1054–1085, findPage 1170)
6. The features are asked, in a fixed order, and the first one that claims the URL wins: post preview, Storefront, Payment, Support Tickets, Service Menu, Tables, Forms, Blog, Unsubscribe, promotion sign-up, Gift Cards, Reservations, Rental, Content Player, Community. (base-app [[...slug]]/page.tsx 114–132)
7. What renders:
   • A feature claimed it and a page with content was found: the page wraps the feature. Its first screen goes above, its second below. A page with one screen, or only data.html, is drawn whole above the feature. (page.tsx 293–294; build-studio/html-renderer.tsx 50–75)
   • A feature claimed it and no page was found: the feature renders inside the page chosen for it, else inside account-layout, else bare. (page.tsx 158–174, 303)
   • No feature, and a page with content: the page.
   • No feature, no page: 404, drawn as the site's own not-found screen (its name, logo and description). (page.tsx 296–302; app/not-found.tsx)

A page record with nothing in it to draw is meant to count as missing ([[...slug]]/feature-template.ts hasRenderableBody 10–18), but on a site with a root page it doesn't: the check also counts root, so an empty page is a blank 200 with no header, and an empty page at a feature's address strips the feature's header and footer. Tested. See Built-in pages and templates.

How a feature claims a URL. It must be on, and the first URL segment, or the name of the page the lookup found, must equal the feature's page. The feature's page is the row's page, else the old per-feature setting (e.g. site.data.storefront.storePage), else the default address. (base-app lib/site-feature-pages.ts isFeatureRoute 107–119, getFeaturePage 93–99, LEGACY 50–57)

When a feature is on. site.data.features comes in two shapes, and both work:

e-commerce means storefront, and ticket-support means ticket. (site-feature-pages.ts ALIASES 44–47, isFeatureEnabled 86–90)

The features

All 15 features in Studio's Site Features, plus the feature routes the code has that Studio doesn't list. "Tested" means checked on the local PhaZZer site with the status shown.

A page you name in a row doesn't have to exist. The feature answers at /<that name> either way, inside account-layout when there's no page to wrap it.

Two features pointed at the same page: the one earlier in the order wins (step 6 above). Tested: Blog and Content Player both set to one page, and Blog rendered.

Routes that are not features

These are fixed. No setting moves them, and no page can take their address.

For the shared header and footer around these screens, see Shared header and footer.

Exceptions

Steps

1. Site Config: read the site

Find the site with repo_find on site ({} for all; match the host to data.hostName or data.domain). Then read it whole with repo_find_one, because find results are partial. Note:

call_appengine GET /site/base-url gives the origin engine links are built on. GET /site/base-url?feature=forms gives the forms link, or url: null with a reason when Forms is off.

Hands on: the site's id (sk), name, its features list as stored, and whether it's the default site. Check: open Studio at /app/welcome → Site Config → Features ("what's switched on"). The switches match data.features. In Build Studio the same drawer opens from the site switcher's "Site config for ".

2. Diagnose: why this URL shows what it shows

Take the URL's host and first path segment and work down. Stop at the first match.

Then work out what the person wanted:

Hands on: the owner of the URL (fixed route, feature, page or nothing) and the fix the person chose. Check: curl -s -o /dev/null -w "%{http_code}" <url> gives the status you predicted. Then look at the rendered page in a browser: the source contains page HTML in a script payload even when nothing is drawn.

3. Site Config: switch a feature on, off, or move it

Only when the person asked. Build the whole new list from the list you read in step 1:

• Keep the shape. In a list of bare names, add the bare name ("reservations"). In a list of rows, add a row ({ "feature": "reservations", "enabled": true }). Mixing them is valid; the site reads both.
• Use a row with a page when engine links need one: Payment, Gift Cards, Content Player, Storefront, or an Unsubscribe landing page. Use the Studio key (storefront, ticket), not the old alias.
• To move a feature, set the row's page to the page's name. Remove page to go back to the default address.
• To switch off and keep the choice, set enabled: false. To switch off fully, remove the name or row.

Write it with repo_update on site: { "datatype": "site", "id": "<sk>", "patch": { "features": [ …the whole new list… ] } }. repo_update merges patch into data one level deep, so the site's other settings stay. The same write by API is POST /repository/update-partial/site/<sk> with the dot-path key { "data.features": [ … ] }.

When the owner next changes any switch in Studio, Studio rewrites the whole list as rows and turns e-commerce into storefront (site-features-section.tsx 77–80, 125). That's expected.

Stop: this changes the live site. Moving a feature changes what an existing URL shows. Before writing, tell the person which addresses will change ("/book will be a 404; bookings move to /appointments, inside that page's header and footer"), and which emails will link where. Wait for yes.

Hands on: the feature's live address. Check: repo_find_one on the site shows the new data.features and everything else as it was. Site Config › Features shows the switch.

4. Check it on the site

• Open the feature's address. It renders the feature, wrapped by its page or account-layout.
• Open the old address if it moved. It now shows the page of that name, or 404.
• For a feature engine emails use, check the link the engine would build. For Forms: GET /site/base-url?feature=forms. For the others, apply the rule in the warning under How a request is answered.
• After a change, open the site's other main pages once to be sure none lost its address to the feature.

When it's done

Tell the person what owns the URL and why, in one line ("/form is the Forms feature, and Forms is off, so it's a 404"). If something changed, say which addresses changed, what's at each now, and which emails link there. Open Site Config › Features and the address on the site.

What it can't do yet

• The page lookup treats the address as a pattern. /h.me opens the home page with a 200. A ( in the first segment gives a 500 instead of a 404. Tested. (appengine site.service.ts findPage 1170–1182)
• Extra segments under an ordinary page are ignored. /home/anything/else shows the home page with a 200, never a 404.
• A signing request for a document with no form links to <site>/sign?token=… (crm.signed.document.ts 864). The site has no /sign route, so that's a 404 unless the site has a page named sign.
• Gift card emails fall back to /gift-card while Gift Cards is off, which is a 404. The engine's comment there says the store always answers it; it doesn't.
• The engine only reads rows under the exact key. A site whose list says e-commerce, or a bare payment, reservations or gift-card, works on the site but gets no feature page in engine links (see each row's fallback).
• Affiliate Marketing and Audio Player switches do nothing to the site. Live Chat only loads the widget.
• A site can't show its own designed 404. The not-found screen is fixed: the site's name, logo and description.

Don'ts

• Don't create a page to "fix" a 404 at a feature's address. Switch the feature on, or leave the 404.
• Don't point a feature's page at a page the site uses for something else. Its content stops showing there. For Forms it also stops showing at its own address.
• Don't trust Studio's missing address line: a feature that's on is live at its default address.
• Don't send data: { … } to update-partial on a site. Use repo_update with patch, or dot-path keys.
• Don't write one feature as a row and drop the rest of the list. Always send the whole list.
• Don't put a page at a fixed route, a static prefix (sitemap…, assets…, tt…) or a feature's address.
• Don't judge a route by a grep of its HTML source. Check the status, then look at it in a browser.