Prerequisites
- Node.js
18or 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
localhostfor 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'inscript-srcwhere required connect-srcfor licence verification and protected package downloadsconnect-srcfor 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
| Error | Cause | Fix |
|---|---|---|
Cannot find package '@nosmai/web-sdk' | The npm package is missing from the app's dependencies | Run npm install @nosmai/[email protected] in the application directory |
| Runtime or model asset request returns 404 | Assets were not copied, or assetBase points to the wrong public URL | Copy all three directories and verify the deployed URL, including any app subpath |
| JavaScript MIME-type error or an HTML response for an asset | The server returned an HTML fallback or an incorrect content type | Serve the copied files directly with the correct MIME types |
webglUnavailable | Browser graphics support is unavailable, or runtime startup failed | Check the underlying error and asset requests; enable hardware acceleration and use a browser with WebGL2 and WebAssembly SIMD |
cameraPermissionDenied | User, browser policy, or iframe policy denied camera access | Use HTTPS or localhost, grant camera access, and permit the camera in the iframe |
| CORS or Content Security Policy error | The browser blocked a runtime asset, licence request, or effect download | Check the blocked URL and allow the required origin and request type |
Next steps
- Add real-time camera effects to a Web app
- Get and apply a licence key
- Check platform support
- Understand filters and authored effects