Preparing your Custom Page build
This page explains how to prepare a build that works the first time. Read the golden rule below: it's the one thing that trips most people up. If you build your page with an AI tool, jump straight to Use AI to build it and copy the prompt.
The golden rule: build for the base path
Your Custom Page is served from a sub‑folder of your domain, not the root:
https://yourdomain.com/c/your-slug/Because of that, every asset your page loads (CSS, JavaScript, images, fonts) has to resolve under that sub‑folder. If your build references assets from the domain root (a leading slash, like /assets/app.js), the browser will look for them at https://yourdomain.com/assets/app.js (which doesn't exist) and your page will load blank or unstyled.
The fix is one setting: tell your build tool that its base path (also called public path, homepage, or base href) is /c/your-slug/. We even check this for you on upload and reject a build whose assets point at the wrong place, with a message telling you exactly what to change.
Step 1: Create the page first to get your slug
- Create the Custom Page (internal name + domain + slug), then save.
- On the form you'll see your exact Build base path:
/c/your-slug/. Copy it. - Your slug locks after the first upload, so this path is stable: you only set it once.
Step 2: Set the base path in your tool
Use whichever matches your stack (replace your-slug):
- Vite: in
vite.config.js:jsexport default { base: '/c/your-slug/' } - Create React App: in
package.json:json{ "homepage": "/c/your-slug/" } - Astro: in
astro.config.mjs:jsexport default { base: '/c/your-slug/' } - VitePress: in
.vitepress/config(building a documentation site? see Documentation sites below):jsexport default { base: '/c/your-slug/' } - Next.js (static export): in
next.config.js, then runnext build && next export:jsmodule.exports = { basePath: '/c/your-slug', assetPrefix: '/c/your-slug/', output: 'export' } - Plain HTML: either reference every asset with a relative path (
assets/app.js, not/assets/app.js), or add a base tag at the top of<head>:html<base href="/c/your-slug/">
Already built without it? Just set the base path and rebuild; you can't fix it by editing the zip.
Step 3: Build and zip
- Run your build (it produces a folder, usually
dist/orbuild/). - Zip that folder's contents, with your entry document (
index.html) at the top. A single wrapping folder (likedist/) is fine: we detect and strip it automatically. - Upload the
.zipon the Custom Page form. We validate, extract and publish it, and notify you when it's live.
Step 4: Declare your embeds and external services (if any)
If your page uses analytics, a booking or form widget, an embedded video, or calls any API from the browser, declare those services under Embeds & external domains on the Custom Page form: otherwise they'll load but silently do nothing. See Embeds, analytics and external services below for how it works. You can edit this list at any time without re‑uploading your build. A fully self‑contained page skips this step.
What your build must contain
- An entry document at the root:
index.htmlby default. If yours is named differently, set the Entry file field on the form to match (a common slip isindext.htmlinstead ofindex.html). - Assets referenced under the base path or relatively: never from the domain root.
- Only static files: HTML, CSS, JS, JSON, images (PNG/JPG/WebP/SVG/GIF/AVIF/ICO), fonts (WOFF/WOFF2/TTF/OTF) and media (MP4/WebM/MP3). No server‑side code.
- A reasonable size: keep it lean; very large unoptimized media is the usual reason a build is too big.
The security sandbox: build within it
Custom Pages run inside a browser security sandbox (so untrusted uploads can never reach other pages' data). Build with these constraints in mind: a page that ignores them will load but parts of it won't work:
- No browser storage:
cookies,localStorage,sessionStorageand IndexedDB are unavailable (the page runs in an isolated origin). Don't rely on them for consent banners, carts, "remember me", etc. - No
eval()/new Function(): use a modern bundle; avoid libraries that eval at runtime. - No client‑side calls to third‑party APIs by default:
fetch/XHR/WebSocket to other origins are blocked unless you declare the service in Embeds & external domains (see below). Otherwise, render content at build time instead of fetching it at runtime. - Allowed: inline and bundled JS/CSS, module scripts (
<script type="module">, any Vite or Astro build), self‑hosted web fonts, runtimefetch()of your page's own bundled files (e.g. adata.jsonyou shipped), external fonts/images/stylesheets/JS libraries over https, forms that POST to an external service, in‑page and new‑tab links, and downloads.
Private pages: one extra step for fonts and module scripts. Because of how browsers request web fonts and module scripts, those requests can't carry your page's access credentials, so on a private page they don't load, and the page appears unstyled or inert. Turn on "Let fonts & module scripts load" on the Custom Page form to fix it. Read the warning there first: it serves your font and
.jsfiles without the access check, so anyone who knows one of those URLs can read it, and a build's.jsusually contains your page's own text and layout. Your entry document and.jsondata files stay protected either way. For a genuinely confidential page, leave it off and have your build embed the fonts directly in the CSS instead. Public pages need nothing: everything just works.
Embeds, analytics and external services
Need analytics, a booking widget, or a form service that submits via JavaScript? Open Embeds & external domains on the Custom Page form and declare what your page uses:
- Known providers: pick services like Google Analytics, Calendly, Tally, HubSpot or YouTube from the list; we maintain the domains each one needs.
- Custom domains: add any other hostname your page calls (e.g.
api.yourservice.com). A leading*.covers subdomains.
Two things to know:
- Declaring anything switches the page to governed mode: it may then only call APIs, embed iframes, and submit forms to itself plus the declared domains. So if you declare your analytics, also declare your form service and any iframe embeds: everything external your page touches goes on the list. Declare nothing and the page keeps the default rules above.
- Declared domains cover your page's own scripts (analytics beacons, JS form submissions, your own API). Iframe embeds and cookie-based widgets (YouTube, Google Calendar, Tally, reCAPTCHA, embedded checkouts) don't work under the sandbox, whichever domains you declare: the browser extends it into every iframe. Serve the page Isolated for those (see Serving: Isolated or Classic); there it runs on its own address with no sandbox.
Single‑page apps and forms
- Client‑side routing? Turn on Single‑page app (SPA) on the form so deep links and refreshes serve your entry document. (Routing that reads from the URL is fine; just remember runtime API calls are blocked: see the sandbox rules above.)
- Have a form? Point it at your own API or a third‑party service (e.g. Formspree) with a normal
method="POST". There's no server here to receive submissions, andfetch‑based submission is blocked: use a plain form post.
Documentation sites (VitePress and friends)
Static documentation generators, such as VitePress, Astro Starlight, Docusaurus (static build) and similar, work as Custom Pages. A few specifics on top of the steps above:
- Set the base path exactly as in Step 2 (VitePress:
base: '/c/your-slug/'in.vitepress/config). - "Clean" URLs work either way. Links that end in
.html(VitePress's default) and extension-less links (cleanUrls: true) both resolve: when a link has no extension, we serve the matching.htmlpage automatically, and a link to a folder redirects to its index (in Classic serving; on an Isolated page, link folders with a trailing slash, as VitePress does). You do not need SPA mode for a docs site. - Remove hosting-provider files before zipping. Files without an extension (like Netlify/Cloudflare's
_headersor_redirects) aren't static web assets and make the whole upload fail. Zip only the site's own files. - The light/dark preference won't persist. The security sandbox has no browser storage, so the theme toggle works while reading but resets on the next visit. Cosmetic and expected: nothing to fix in your build.
- Search: the generator's built-in local search works out of the box. A hosted search service (e.g. Algolia DocSearch) calls a third-party API: declare it under Embeds & external domains.
- Confidential docs don't belong on a private page with the fonts-and-scripts toggle. A docs generator packs each page's full text into its
.jsfiles, so on a private page the toggle described above makes your content readable to anyone who knows the URLs. If your documentation is genuinely confidential, keep it off Custom Pages for now.
Use AI to build it
If you're generating your page with an AI tool (or coding assistant), paste this prompt and replace your-slug with your page's slug. It tells the AI everything it needs to produce a build that uploads cleanly:
Build me a self-contained STATIC website that will be hosted at the sub-path "/c/your-slug/" (NOT the domain root) and served inside a browser security SANDBOX (isolated/opaque origin). Follow these rules exactly.
ASSET ROUTING
1. Entry document: produce index.html at the ROOT of the build output.
2. Base path: configure the build's base / public path / homepage to "/c/your-slug/" so every asset (CSS, JS, images, fonts) is referenced under that prefix.
- Vite: set base: "/c/your-slug/" in vite.config.
- Create React App: set "homepage": "/c/your-slug/" in package.json.
- Astro: set base: "/c/your-slug/".
- VitePress: set base: "/c/your-slug/" in .vitepress/config.
- Next.js: set basePath and assetPrefix to "/c/your-slug/" and use static export (output: "export").
- Plain HTML: use relative asset paths (e.g. "assets/app.js"), or add <base href="/c/your-slug/"> in <head>.
3. NEVER reference an asset from the domain root with a leading slash (e.g. "/assets/...", "/favicon.ico"). Use the base path or relative paths only.
FILE TYPES
4. Use only static files: html, css, js, json, images (png/jpg/jpeg/webp/svg/gif/avif/ico), fonts (woff/woff2/ttf/otf), media (mp4/webm/mp3). No server-side code (no PHP, Node endpoints, APIs).
SANDBOX CONSTRAINTS (the page runs in an isolated origin: ignoring these makes features silently fail)
5. Do NOT use cookies, localStorage, sessionStorage or IndexedDB: browser storage is unavailable. Don't build cookie-consent persistence, carts, or "remember me".
6. Do NOT use eval() or new Function(); use a modern build that does not eval at runtime.
7. Third-party APIs (fetch / XHR / WebSocket) and iframe embeds only work for domains I explicitly allow in the hosting platform. List every external domain the page calls or embeds (analytics endpoints, form APIs, widget iframes) at the end of your answer so I can allow them. When in doubt, render data at build time instead of fetching at runtime.
8. Forms must submit to an external service (e.g. Formspree): a plain <form method="POST" action="https://..."> always works; fetch-based submission works only if the service's domain is on my allowed list (include it in the domain list from rule 7). There is no backend here.
8b. Iframe embeds (YouTube, calendars, form widgets) and anything needing cookies or storage inside the page only work when the hosting platform serves the page "Isolated" (its own origin, no sandbox). If the page uses any of these, say so explicitly at the end of your answer (next to the domain list from rule 7) so I can choose that mode.
9. Allowed: inline and bundled JS/CSS; external fonts/images/stylesheets/JS libraries loaded over HTTPS from their own CDNs; same-tab and new-tab links; downloads.
OUTPUT
10. Keep the build small (ideally under ~50 MB zipped); optimize images and avoid huge media.
11. If it uses client-side routing, ensure deep links work by serving index.html for unknown routes (I will enable "Single-page app" mode on upload).
Deliver the final build folder, ready to zip (with index.html at its root) and upload.Troubleshooting
- Page loads blank or unstyled → the base path isn't set. Rebuild with
base/homepage/<base href>=/c/your-slug/. - "The build is missing its entry document" → there's no
index.htmlat the root of the zip, or it's misnamed. Fix the name (or set the Entry file field to match) and re‑zip. - "File type not allowed" → remove any server‑side or executable files, and any hosting‑provider files without an extension (
_headers,_redirects); keep only static web assets. - Deep links or refresh show "not found" → for a client‑side‑routed app, turn on Single‑page app (SPA) mode. (Docs‑site links without
.htmlresolve automatically: no SPA mode needed.) - The dark/light toggle doesn't stick between visits → expected: the sandbox has no browser storage to remember it. Nothing to fix.
- "Assets point at the domain root" → your build still uses leading‑slash paths; set the base path and rebuild.
- A widget or analytics loads but silently does nothing → its API calls are blocked. Declare the service under Embeds & external domains, and remember that once you declare anything, every external domain the page calls, embeds or posts forms to must be on the list.
- An iframe embed (YouTube, Google Calendar, Tally, reCAPTCHA, embedded checkout) shows errors or stays blank → embedded widgets can't run inside the sandbox. Serve the page Isolated.
- Changed the embed settings but nothing happened? → hard‑refresh: a public page's files are cached by the browser for up to 5 minutes.
With Claude
With the Claude connector, Claude can build the site with you and upload the result as a version of your Custom Page, following this guide (base path, no outside requests, the sandbox).
- Connection permissions: Create and edit custom pages to upload to a private page; Make custom pages public for a public one.
- Goes live: uploading to a public page and activating the version publishes it.
Try asking:
- "Build a one-page Astro site for our event with base /c/event/ and upload it to the event Custom Page."
- "My build shows a blank page after uploading: check it against the Custom Pages rules."