AMWdev.amoosed.com For developers

FOR DEVELOPERS / INTEGRATION

Ship a verified second experience.

Two supported routes: start from an independent project, or integrate the compiler output and runtime into an existing HTTPS site.

Tutorial 1: create an AmoosedWeb site

  1. Install Node.js 22+ and amoosedweb-compiler.
  2. Initialize a project. It contains an ordinary site/, a carrier-backed app/, document.json, bundle.json, and local build scripts.
  3. Edit the files, build, inspect the generated output, then package a release.
npm install -g amoosedweb-compiler
amw init my-site
cd my-site

# Edit site/, app/, document.json, and bundle.json.
build.cmd                        # Windows
# sh build.sh                    # macOS or Linux

amw serve builds/local-0001     # use the folder printed by the build
release.cmd YOUR_PAGES_PROJECT   # local package; does not upload
# sh release.sh YOUR_PAGES_PROJECT on macOS or Linux

A minimal bundle.json selects an existing binary file under site/ as a carrier:

{
  "document": "document.json",
  "carriers": ["media/scene.png"],
  "chunkSize": 65536,
  "keyId": "hello-members",
  "protected": ["members/"]
}

The starter supplies media/scene.png, the members example, and the matching document. Replace these with your own files and keep the carrier path accurate. The compiler stores a generated member key in ignored .amw/keys/. Never copy that directory into public output.

Release boundary. Deploy only the verified distribution/release-NNNN/pages/ folder. Its source-and-key snapshot stays private. The site’s existing media must remain byte-for-byte intact after hosting.

Tutorial 2: integrate an existing HTTPS product

Keep the product’s ordinary pages and media at their current URLs. Build an AmoosedWeb project whose site/ is the static site build and whose app/ holds the optional experience. The compiler overlay changes only selected carrier bytes.

  1. Choose existing binary URLs as carriers and list them in bundle.json. Retain the original media for later rebuilds.
  2. Compile the project into a new output folder and verify it.
  3. Export the version-matched site runtime and deploy its files at the exact paths given in route-contract.json.
  4. Configure cold /amoosed.com/app/* visits to return the boot HTML with the listed security headers. Keep all runtime files on the same HTTPS origin as the site.
  5. Publish the verified media overlay at the original paths and run check-host against the deployed origin.
amw build-project my-site my-site/public
amw verify-site my-site/public
amw export-runtime ./amw-routes

# Deploy my-site/public plus the exported /amoosed.com/ routes.
# Apply amw-routes/route-contract.json to your host.

amw check-host https://your-site.example/

For a private external index, check-host also takes the separately delivered .amwkey or index ICO. Use AMW_MEMBER_KEY_FILE when checking protected resources. The complete host requirements are in SITE-INTEGRATION.md and WEBAPP.md.

Same-origin scripts can access keys imported into that origin. Audit the host’s JavaScript and third-party scripts before putting confidential content there. The path prefix and browser extension are not a security boundary against scripts on the same origin.

Tutorial 3: consume a site from your product

Use the Node.js or .NET Reader when your application needs resource metadata or verified downloads. The Reader checks part hashes and the reconstructed resource hash. It never overwrites an existing output file.

npm install amoosedweb-reader
node examples/node-reader.mjs https://your-site.example/ ./downloads

The downloadable Node.js example lists resources, chooses a public download, and writes it to the directory you pass. The C# example provides the equivalent .NET workflow. For a private index, supply the index key file; for member resources, supply the separate member key file. Keep both in private storage.