Effects Web
Effects / Get started / Installation / Web

Install the Nosmai Effects SDK for Web

Updated August 27, 2026

Install Nosmai Web SDK 1.0.0 from npm, serve its runtime assets, and check your browser setup.

Prerequisites

  • Node.js 18 or later, or the higher minimum required by your build tool
  • A browser app with an ESM-compatible bundler, such as Vite
  • HTTPS for deployed environments or localhost for development
  • Browser support for camera access, WebGL2, WebAssembly SIMD, and Web Crypto
  • A Nosmai Web licence key registered for your application's Web origin

Run the SDK in the browser. In an application that uses server-side rendering, initialize it after the page mounts on the client.

Requirement details

  • Secure context means HTTPS in production or an approved local development address. Browsers normally block camera access on an insecure page.
  • Bundler prepares the app's JavaScript or TypeScript for the browser.
  • WebGL2 provides accelerated browser graphics.
  • WebAssembly SIMD is required for the runtime. The SDK selects a compatible engine automatically; serve both engine directories described below.
  • Web Crypto provides browser security functions used by the SDK.

Install from npm

Run this command in your application's root directory:

npm install @nosmai/[email protected]

This guide targets version 1.0.0. Commit the updated package manifest and lockfile so your team and deployment use the same dependency version.

Import the public API from the installed package:

import { Nosmai, SDK_VERSION } from '@nosmai/web-sdk'

React applications can also use the optional @nosmai/web-sdk/react entry point with React 18 or later. The base SDK works without React.

Copy the runtime assets

The JavaScript import and the runtime assets are both required. Copy these directories from the installed package into a directory your app serves:

node_modules/@nosmai/web-sdk/
  engine/
  engine-baseline/
  models/

For Vite and other tools that serve a public directory, create prepare-nosmai-assets.mjs in your application's root:

import { cp, mkdir } from 'node:fs/promises'
import { createRequire } from 'node:module'
import { dirname, join, resolve } from 'node:path'

const require = createRequire(import.meta.url)
const packageRoot = dirname(require.resolve('@nosmai/web-sdk/package.json'))
const destination = resolve('public/nosmai')

await mkdir(destination, { recursive: true })

for (const directory of ['engine', 'engine-baseline', 'models']) {
  await cp(join(packageRoot, directory), join(destination, directory), {
    recursive: true,
  })
}

Run the script before starting development or building for deployment:

node prepare-nosmai-assets.mjs

The resulting public directory should contain:

public/nosmai/
  engine/
  engine-baseline/
  models/

Keep the directory names and file contents unchanged. Repeat the copy whenever you change SDK versions, and deploy the JavaScript package and runtime assets from the same release together. Include this copy step in your deployment build so it also runs on a clean checkout.

Set the asset location

Pass the public URL of the directory containing all three asset directories as assetBase:

import { Nosmai } from '@nosmai/web-sdk'

const result = await Nosmai.initialize('NOSMAI-YOUR-WEB-API-KEY', {
  assetBase: '/nosmai',
})

if (!result.ok) {
  throw result.error ?? new Error('Nosmai initialization failed')
}

Replace the placeholder with your Web licence key from Nosmai Console. The SDK handles licence verification when you attach a preview canvas. A successful initialize call confirms the configuration step; check Nosmai.instance.licenceState or the licenseStatusChanged event after attaching the canvas for the licence result.

In this example, public/nosmai is served at /nosmai. If your app is deployed under a subpath, use the corresponding URL, such as /my-app/nosmai. assetBase can also be an absolute URL to your asset host. Cross-origin assets must have appropriate CORS headers.

Serve JavaScript files with a JavaScript MIME type and .wasm files as application/wasm. Check that asset requests return their actual contents; a single-page application's HTML fallback must not replace missing asset files.

Configure browser security

The document and any embedding iframe must permit camera access. A restrictive Content Security Policy must also allow:

  • the application scripts and runtime JavaScript from your asset host
  • WebAssembly compilation, using 'wasm-unsafe-eval' in script-src where required
  • connect-src for licence verification and protected package downloads
  • connect-src for runtime and model asset downloads
  • image and media sources referenced by authored packages

When embedding the camera in an iframe, allow the camera explicitly:

<iframe src="https://camera.example.com" allow="camera"></iframe>

Do not deploy the camera experience over plain HTTP.

Use a current browser with WebGL2 and WebAssembly SIMD support. Hardware acceleration is recommended for real-time camera processing. Browser support alone does not guarantee the same performance on every device; test your target devices with the effects your app will use.

Runtime downloads and caching

Measure the application JavaScript, runtime assets, and effect packages separately. The engine and model assets load when you attach the preview canvas, so include those requests when measuring first-start time. Cache assets by SDK release and invalidate old cached files when upgrading.

Verify it worked

Confirm the installed version:

npm ls @nosmai/web-sdk

It should list @nosmai/[email protected]. Then add this to a browser entry module:

import { SDK_VERSION } from '@nosmai/web-sdk'

console.log('Nosmai Web SDK:', SDK_VERSION)

Run your application's build command and confirm the import resolves. In the browser, the console should report Nosmai Web SDK: 1.0.0.

Check that your development server and production deployment serve files from all three copied directories. Runtime requests should return files successfully, without CORS, MIME-type, or Content Security Policy errors. Engine and model requests begin when you call Nosmai.instance.attach(canvas) with a canvas already mounted in the page.

The Web quickstart covers the camera preview and applying an effect.

Common errors

ErrorCauseFix
Cannot find package '@nosmai/web-sdk'The npm package is missing from the app's dependenciesRun npm install @nosmai/[email protected] in the application directory
Runtime or model asset request returns 404Assets were not copied, or assetBase points to the wrong public URLCopy all three directories and verify the deployed URL, including any app subpath
JavaScript MIME-type error or an HTML response for an assetThe server returned an HTML fallback or an incorrect content typeServe the copied files directly with the correct MIME types
webglUnavailableBrowser graphics support is unavailable, or runtime startup failedCheck the underlying error and asset requests; enable hardware acceleration and use a browser with WebGL2 and WebAssembly SIMD
cameraPermissionDeniedUser, browser policy, or iframe policy denied camera accessUse HTTPS or localhost, grant camera access, and permit the camera in the iframe
CORS or Content Security Policy errorThe browser blocked a runtime asset, licence request, or effect downloadCheck the blocked URL and allow the required origin and request type

Next steps

References

Nosmai

An AR and AI company. Founded on the idea that the next decade of software will be visual, and that the tools for it should be within reach of anyone building.

Newsletter

Product updates and release notes. No spam.

© 2026 nosmai, inc · all rights reserved