Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

Host on GitHub Pages

GitHub Pages serves plain files. Wisp writes every parameterless page as HTML, so the site needs no server.

Build

wisp build --static          # dist/ (--out <folder>)

--spa is --static plus an index.html fallback. The same build works for GitLab Pages and S3.

Deploy

wisp deploy init pages

This writes .github/workflows/deploy.yml: build with --static, then actions/upload-pages-artifact and actions/deploy-pages on push to main. It reads no secrets. In the repository, set Settings, Pages, Source to GitHub Actions. --force replaces the file.

Environment

  • SITE_URL (for example https://me.github.io/my-app): the address that sitemaps, feeds and absolute links use. Set it when you build.
  • A project site lives at https://me.github.io/my-app/: set base = "/my-app" under [package.metadata.wisp] in Cargo.toml (or WISP_BASE=/my-app when you build). Links in your pages (<a href="/about">, src, action, srcset), redirects, typed routes, the sitemap, the manifest and Wisp's own /_app/ files get the prefix at build; you write plain /about. dist/ is the folder GitHub serves at /my-app/, so its files stay at its root. wisp preview --static serves it under the base, and a request outside it is a 404. A user or organization site (me.github.io) needs no base.
  • assets = "https://cdn.example.com" (or WISP_ASSET_BASE) links the built /_app/ files from a CDN host; it must be https://, with no slash last and no ?, #, ;, ,, quote or space. A bad base or assets stops the build with the fix.
  • There is no server, so WISP_SECRET and the runtime variables do not apply. See Environment variables.

Limits

  • Forms need a server: the export warns for each page with actions, and for each exported page whose HTML holds a form that posts.
  • A route with actions or a +server.rs needs a server (the export warns).
  • A [params] route lists its pages with entries.
  • Pages ignores _headers and sends every file with Cache-Control: max-age=600, so the hashed /_app files are not kept as immutable, and the app's security headers (CSP and the rest) are not sent. A host that reads _headers (Netlify, Cloudflare Pages) sends both.

Static Assets

  • static/ and the /_app files are written into dist/, with an empty .nojekyll. Pages deployed from a branch runs Jekyll, which leaves out _app/ and every other _ folder; the Actions workflow does not, and the file is harmless there.
  • Saved tables do not exist here: there is no process to keep them.

More

Deploying, Hosting.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.