Build your first animated page

In this tutorial we will install anvil, author a single animation, see it play in the browser, and deploy it to the edge. By the end you will have a live page with a spinning 3-D shape on it. We will not stop to explain the choices along the way — that is what the Explanation pages are for. Follow the steps in order.

1. Install¶

Create a folder and add anvil. anvil is not on npm yet, so install it from the GitHub repository:

mkdir my-animations && cd my-animations
npm init -y
npm install github:acoyfellow/anvil svelte

Once a release is published the package name will be @acoyfellow/anvil; the import paths below already use it.

2. Write a spec¶

Every animation in anvil is one JSON object called a SceneSpec. Create hero.json and paste this in:

{
  "id": "hero",
  "kind": "three",
  "width": 480,
  "height": 480,
  "env": { "background": "#0b0b12" },
  "objects": [
    {
      "name": "knot",
      "geometry": { "type": "torusKnot" },
      "material": { "type": "standard", "color": "#5b8cff", "metalness": 0.7 }
    }
  ],
  "lights": [
    { "type": "ambient", "intensity": 0.4 },
    { "type": "directional", "intensity": 1.2, "position": [3, 4, 5] }
  ],
  "animate": [
    { "target": "knot", "property": "rotation", "axis": "y", "speed": 0.6 }
  ]
}

You will see, once it renders, a blue metallic knot turning slowly.

3. Render it¶

Create App.svelte and drop the one component anvil gives you onto the page:

<script>
  import { Anvil } from "@acoyfellow/anvil";
  import spec from "./hero.json";
</script>

<Anvil {spec} />

That is the whole integration. The component renders a placeholder during server rendering and, when it mounts in the browser, loads the right renderer and starts the animation.

4. See it move¶

Run your Svelte dev server (whatever your project uses — Vite, SvelteKit, or the anvil gallery worker). Open the page. The knot is turning. You have built your first animated page.

Where to go next¶

You now have the shape of the whole workflow: write a spec, drop in <Anvil>. To accomplish specific tasks — a loading spinner, a success check, serving specs from a Worker — see the How-to guides. To understand why anvil works this way, read the Explanation.