Self-hosting Stork

The simplest method of getting started with Stork is to load the Javascript from the Stork CDN. The Javascript library will load the WASM blob from the same CDN. The files will both be the latest version of the Stork library, and are guaranteed to work together. This simplifies integration: you don't have to host the script or the WASM binary, and you don't have to make sure to coordinate the version of the two.

However, loading an external script from a third-party CDN is not always ideal. To support users who want to self-host Stork, the Stork frontend lets you load the Javascript and WebAssembly from your own site.

  1. Download the matching JS/WASM files. Visit the latest Stork Release page on Github and download the Javascript and WASM build artifacts.

  2. Serve those files from your web server. Upload the Javascript and WASM files to your web server or web host and serve them publicly as you would a stylesheet or image.

    Make sure to serve the WASM file with the application/wasm MIME type. If you are putting these files behind your CDN, make sure to forward the Content-Type header from your file source, through that CDN.

  3. Initialize Stork on your webpage with your WASM's URL. The Advanced Javascript page describes the stork.initialize() method, which instructs Stork to load the WASM. Make sure you call this method -- even if you're using the simpler, stork.register() API -- before calling any other Stork methods:

<script src="https://your-url.com/stork.js"></script>
<script>
stork.initialize("https://your-url.com/stork.wasm")
stork.register("yourIndexName", "https://your-url.com/index-file.st")
</script>

Writing Content-Security Policies

Stork relies on the ability to execute WASM in the browser. Most Content-Security Policy definitions will block WASM execution by default. You might see this manifest as a generic WASM load error:

Uncaught (in promise) StorkError: Error while loading WASM at /stork.wasm

Wasm code generation disallowed by embedder

Unfortunately, there are not many good options to both have a restrictive CSP and execute WASM in the browser, even if you self-host the WASM file. In order for Stork to function, you'll have to allow WASM execution within your script-src directive. The following CSP is the minimally permissive CSP that will still allow Stork to function in all major browsers:

default-src 'self'; script-src 'unsafe-eval';

Google Chrome supports the 'wasm-unsafe-eval' (or sometimes, 'wasm-eval') policies in your script-src directive to allow WASM execution. However, as of this writing, Safari and Firefox require that you specify the unsafe-eval policy in your script-src directive, which makes your restrictive CSP much less restrictive.

!

Note:

Future work might include investigating usage of the strict-dynamic directive, which may allow punching a small hole in a CSP to allow for targeted WASM execution permissions for a given Javascript file.

Was this page helpful?

If you see an issue, please file a bug!

© 2019–2023. Stork is maintained by James Little, who's really excited that you're checking it out.

This site is open source. Please file a bug or open a PR if you see something confusing or incorrect.

Logo art by Bruno Monts, with special thanks to the fission.codes team. Please contact James Little before using the logo for anything.