Skip to main content

Deploying to Flexweg

Once you have a dist/ folder (either built locally with npm run build or downloaded from a release), deploying to Flexweg means uploading two folders to two specific locations on your Flexweg site.

What goes where​

dist/
├── admin/             → upload to /admin/ on Flexweg
└── theme-assets/      → upload to /theme-assets/ on Flexweg (site root)

The split mirrors the public site layout:

  • Every published page contains <link rel="stylesheet" href="/theme-assets/<theme-id>.css"> — that's why theme-assets/ lives at the site root, not under /admin/.
  • The admin SPA lives entirely under /admin/ (or whatever you renamed the folder to — see Renaming the admin folder).

First deploy​

  1. Open your Flexweg dashboard → File manager.
  2. Create a folder named admin/ at the root of your site.
  3. Upload the contents of dist/admin/ (not the folder itself — its contents) into the admin/ folder. After this you should have on Flexweg:
/admin/
├── index.html
├── config.js
├── external.default.json
├── assets/
├── runtime/
├── plugins/
│   ├── core-seo/
│   ├── flexweg-archives/
│   ├── flexweg-rss/
│   ├── flexweg-search/
│   └── flexweg-sitemaps/
└── themes/
    ├── corporate/
    └── magazine/
  1. Upload the contents of dist/theme-assets/ into your site root. After this:
/theme-assets/
├── corporate.css
├── corporate-menu.js
├── corporate-posts.js
├── default.css
├── default-menu.js
├── default-posts.js
├── magazine.css
├── magazine-menu.js
└── magazine-posts.js
  1. Open https://<your-site>/admin/ in your browser. The first-run setup wizard appears. Follow First-run setup form.

Subsequent deploys​

When you have a new build (e.g. after updating the admin's source code):

  1. Re-upload dist/admin/ entirely. Replace whatever is on Flexweg. This is safe — your user state lives in Firestore, not in the admin folder.
  2. Re-upload dist/theme-assets/ to refresh the public-facing theme CSS. Existing published pages reference these files, so updating them takes effect on the next page load (visitors see the new CSS without you re-publishing every page).
  3. Open the admin — no setup wizard appears (config.js was already filled). Hard-refresh in your browser (Cmd+Shift+R / Ctrl+F5) to bypass any cached old admin assets.

What you DON'T need to redeploy:

  • Your published pages (they're under /<category>/ and /<page-slug>.html etc., untouched by an admin upgrade)
  • /menu.json, /posts.json, /sitemap-*.xml, /rss.xml — these stay as the publisher last wrote them
  • Your media files under /media/

What gets refreshed:

  • The admin SPA (/admin/) — a fresh build
  • The public theme CSS / JS (/theme-assets/) — must match the new admin to avoid mismatched references
Why redeploying admin/ is safe

The list of installed externals (which plugins/themes are active vs uninstalled), all your post drafts, your settings, your plugin configs — none of these live in admin/. They live in Firestore (settings/externalRegistry, posts/{id}, settings/site, settings/site.pluginConfigs, etc.). Redeploying admin/ refreshes the admin code without touching any of that.

This is a deliberate architectural choice — see How it works and Operations: Updating the admin.

Upload methods​

Flexweg's File manager UI lets you drag-and-drop folders. For larger admins or batch deploys, two alternatives:

Via Flexweg's "ZIP and drop" feature​

  1. ZIP dist/admin/'s contents (not dist/admin/ itself; ZIP its contents).
  2. Drag the ZIP into Flexweg's file manager.
  3. Flexweg unzips it server-side. Make sure the destination is /admin/ (or your renamed folder).

Same for dist/theme-assets/ → ZIP its contents, drop, target /theme-assets/.

Via the Files API​

If you have many sites or want to script the deploy, use Flexweg's Files API:

# Upload one file
curl -X POST "https://www.flexweg.com/api/v1/files/upload" \
  -H "X-API-Key: $FLEXWEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"admin/index.html","content":"<base64-or-utf8>"}'

A small shell or Node script can walk dist/ and POST every file. The Files API supports both UTF-8 (text files) and base64 (binary) uploads.

Verifying the deploy​

After uploading:

  1. Open https://<your-site>/admin/ — admin shell loads (login screen or dashboard).
  2. Open browser DevTools → Network tab → reload. Verify:
    • index.html returns 200
    • config.js returns 200 with your Firebase values (or null on first deploy)
    • assets/index-<hash>.js returns 200
    • external.default.json returns 200 with the bundled plugins/themes list
  3. Console should show no errors. Common issues:
    • NS_ERROR_CORRUPTED_CONTENT / MIME type "text/html" on assets/index-<hash>.js → the file isn't actually deployed; Flexweg is returning the SPA fallback. Re-upload missing files.
    • Could not read external registry → check that external.default.json is at /admin/external.default.json.
    • 404 on runtime/react.js → the runtime/ folder didn't upload. Re-upload it.

Renaming the admin folder​

You can rename /admin/ to anything — /erf34f654GH3/, /dashboard/, whatever — for a slight obscurity boost. The admin auto-detects its folder name on every load.

See Renaming the admin folder for the rules and caveats.

Continue​