How to package your project for the AE Gallery

Quick start

The Claude packaging prompt

Before you zip a folder, run this prompt through Claude (Code, CLI, or Desktop). Claude will read your files, identify the entry HTML, trace references, flag external-CDN issues, and tell you what to drop. It adapts to your project far better than any static heuristic could — and you stay in control of the final manifest.

Run the prompt, review Claude's manifest, zip only the KEEP list, then drop the zip onto /upload. Ambiguous files: your call.

Packaging rules

Enforced at upload time (both client-side pre-check and server-side). Numbers below come directly from the governance config; if a limit changes, this page updates too.

Hard-rejected patterns

Anything matching these is rejected at upload — it won't be persisted.

Soft warnings

These won't block your upload, but we'll surface a "did you mean to include this?" notice so you can double-check. Useful when Claude's cleanup pass misses something.

Allowed file types

The Gallery accepts standard web assets. Anything outside this list is rejected — we don't host executables, archives-within-archives, or arbitrary binary formats.

External CDNs (CSP allowlist)

The Gallery's Content Security Policy restricts which external origins your content can load resources from. If your HTML references a CDN not on this list, the browser will block it and your artifact will render broken.

Need a different CDN? Two options: bundle the dependency into your own JS file (pre-zip), or request an allowlist addition. We intentionally keep this list small — every external origin is a surface area for supply-chain risk.

Entry HTML convention

Every zipped artifact needs an entry HTML file at the zip root. Preference is index.html. Other .html at the root works if there's only one — we auto-rename it to index.html on our side.

Recommended folder structure

my-project/
├── index.html         ← entry
├── styles.css
├── app.js
└── assets/            ← by convention (not required)
    ├── logo.svg
    ├── hero.jpg
    └── chart-data.json

Troubleshooting

My upload was rejected — "File type not allowed"

Check the allowed file types list. Most commonly: uploading a .zip inside your .zip, or a design-source file (.psd/.ai/.fig/.pptx). Drop those before re-zipping.

The Gallery says my HTML renders, but my images are broken

Almost always one of: (1) absolute paths like src="/assets/logo.png" that don't resolve under /a/{link-name}/, or (2) external CDN URLs not on the allowlist. Switch to relative paths and/or inline the asset.

My script doesn't run

The Gallery runs your HTML in a sandboxed iframe without allow-same-origin. That means document.cookie, localStorage, indexedDB, and any same-origin-dependent APIs silently fail. Scripts run, but state can't persist. If you need state, externalize it (the consumer of the link can bookmark).

My page has a "Failed to load resource" for a font

External fonts need CORS. Google Fonts serves CORS-correctly. Self-hosted fonts (bundled in your zip) work with no special config. Fonts from CDNs not on our allowlist will 404.

My fetch() or XHR fails

The sandboxed iframe has an opaque origin, so most fetch calls are treated as cross-origin. fetch('./data.json') to a file in your own zip works once we ship multi-file support. External API fetches need explicit connect-src allowlisting; ask if you need one.

My zip is over 100 MB

Check for images you didn't compress. A single 4K PNG can be 30 MB; the same image exported as WebP at 85% is typically 500 KB-2 MB. Or you're shipping node_modules/ (don't). Run the Claude prompt — it'll flag the heavy stuff.

I want to use Tailwind / React / Vue / some framework

Two paths: use the framework's CDN build if the host is on our allowlist (Tailwind via cdn.tailwindcss.com — not currently allowlisted, ask); or bundle everything into your JS/CSS files pre-zip with your tool of choice.

Something else broke

Ping Matt. We triage from there.