Toolchain Setup

AvatarKit uses WebAssembly for avatar rendering. Your build tool must serve .wasm files with the correct MIME type and keep them as external assets instead of inlining them into JavaScript.

Required: Complete this setup before initializing the Web SDK. Missing WASM configuration commonly appears as a .wasm 404, an incorrect MIME type error, or a failed SDK initialization.

Vite
Next.js

Use the official AvatarKit Vite plugin:

vite.config.ts

import { defineConfig } from 'vite'
import { avatarkitVitePlugin } from '@spatius/avatarkit/vite'

export default defineConfig({
  plugins: [
    avatarkitVitePlugin(),
  ],
})

What the plugin configures

The Vite plugin handles the WASM requirements for both development and production:

Serves .wasm files as application/wasm in the Vite dev server
Copies AvatarKit WASM files into dist/assets/ during builds
Generates a _headers file for Cloudflare Pages deployments
Configures Vite options such as optimizeDeps, assetsInclude, and assetsInlineLimit

Manual Vite configuration

Use this only if you cannot use avatarkitVitePlugin():

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['@spatius/avatarkit'],
  },
  assetsInclude: ['**/*.wasm'],
  build: {
    assetsInlineLimit: 0,
    rollupOptions: {
      output: {
        assetFileNames: (assetInfo) => {
          if (assetInfo.name?.endsWith('.wasm')) {
            return 'assets/[name][extname]'
          }
          return 'assets/[name]-[hash][extname]'
        },
      },
    },
  },
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      if (req.url?.endsWith('.wasm')) {
        res.setHeader('Content-Type', 'application/wasm')
      }
      next()
    })
  },
})

Wrap your Next.js config with withAvatarkit:

next.config.mjs

import { withAvatarkit } from '@spatius/avatarkit/next'

export default withAvatarkit({
  // ...your existing Next.js config
})

What the wrapper configures

The Next.js wrapper handles the Webpack and response-header work needed for AvatarKit WASM assets:

Fixes asset path resolution so WASM files load from /_next/static/chunks/
Copies .wasm files into static/chunks/ during the client build
Adds the application/wasm response header for /_next/static/chunks/*.wasm
Preserves any existing webpack and headers configuration

Composing with other wrappers

If your project already uses another Next.js config wrapper, apply withAvatarkit to the final wrapped config:

next.config.mjs

import { withAvatarkit } from '@spatius/avatarkit/next'
import withOtherPlugin from 'other-plugin'

export default withAvatarkit(withOtherPlugin({
  // ...your existing Next.js config
}))

Verify Setup

After configuring your toolchain, run your app and confirm the AvatarKit .wasm request succeeds:

The request should return 200
The response header should include Content-Type: application/wasm
The file should be loaded as a separate .wasm asset, not inlined into JavaScript

If the WASM request fails, use the Vite plugin or Next.js wrapper above before debugging SDK initialization code.

​Verify Setup

Verify Setup