Skip to main content

xrift.json Configuration

Item settings are stored in xrift.json at the project root, under the item key (the same file used for worlds).

Example​

{
"item": {
"distDir": "./dist",
"title": "My Item",
"description": "A sample item",
"thumbnailPath": "thumbnail.png",
"buildCommand": "npm run build",
"ignore": [
"**/.DS_Store",
"**/Thumbs.db",
"**/*.map"
],
"permissions": {
"allowedDomains": ["api.example.com"],
"allowedCodeRules": ["no-network-without-permission"]
}
}
}

Fields​

FieldTypeDescription
distDirstringThe directory containing the build artifacts to upload
titlestringItem title (prompted at upload time if not set)
descriptionstringItem description (prompted at upload time if not set)
thumbnailPathstringPath to the thumbnail image (relative to distDir)
buildCommandstringBuild command run before upload
ignorestring[]Glob patterns of files excluded from the upload
permissionsobjectPermissions required by the item
Difference from World Configuration

Item configuration shares most fields with worlds, but physics, camera, and outputBufferType are world-only. Items do not use them.

Field Details​

distDir​

The directory to upload. This is the build output directory that contains Module Federation's remoteEntry.js.

{
"item": {
"distDir": "./dist"
}
}

title / description​

Item title and description. These are optional, but when set they skip the corresponding prompts in xrift upload item.

{
"item": {
"title": "My Awesome Item",
"description": "An interactive 3D item"
}
}

thumbnailPath​

Path to the item's thumbnail image, relative to distDir.

{
"item": {
"distDir": "./dist",
"thumbnailPath": "thumbnail.png"
}
}

In this case, dist/thumbnail.png is used as the thumbnail.

Recommended size: 512x512 pixels

buildCommand​

A command executed automatically before upload when running xrift upload item.

{
"item": {
"buildCommand": "npm run build"
}
}

Setting this removes the need to build manually before each upload.

ignore​

Glob patterns of files to exclude from the upload.

{
"item": {
"ignore": [
"**/.DS_Store",
"**/Thumbs.db",
"**/*.map"
]
}
}

permissions​

Declares the permissions the item requires. Declared permissions are considered during review and apply when the item is used inside a world.

FieldTypeDescription
allowedDomainsstring[]External domains the item communicates with
allowedCodeRulesstring[]Code security rules that need to be relaxed

Basic Setup​

{
"item": {
"permissions": {
"allowedDomains": ["api.example.com", "cdn.example.com"],
"allowedCodeRules": ["no-navigator-access", "no-network-without-permission"]
}
}
}

allowedDomains​

Specifies external domains the item's code communicates with. @xrift/code-security statically analyzes the code and blocks communication to domains not listed here.

allowedCodeRules​

Declares which rules of the @xrift/code-security code check should be relaxed because the item needs them. Only the rules listed under "Relaxable rules" can be relaxed.

Relaxable rules​
RuleWhat it relaxes
no-new-functionDynamic code generation with the Function constructor
no-string-timeoutString arguments to setTimeout / setInterval
no-javascript-blobDynamic script generation with JavaScript Blobs
no-obfuscationObfuscated code patterns
no-network-without-permissionfetch, WebSocket, etc. whose destination cannot be read from the code (requests with a string destination are checked against allowedDomains)
no-rtc-connectionWebRTC (RTCPeerConnection) connections (see below)
no-dangerous-dominnerHTML and script element injection
no-navigator-accessAccess to geolocation, camera, microphone, clipboard, etc.
no-global-overrideOverriding global objects (window, document, etc.)
Rules that cannot be relaxed​

The following rules are not relaxed even if listed in allowedCodeRules. Any violation makes the upload fail.

RuleWhat it forbids
no-evalExecuting strings as code with eval()
no-external-importImporting JavaScript modules from external URLs
no-storage-accessAccess to localStorage / sessionStorage
no-cookie-accessReading and writing cookies
no-indexeddb-accessAccess to IndexedDB
no-storage-eventListening to storage events from other tabs
no-sensitive-api-overrideOverriding security-critical APIs such as fetch
no-prototype-pollutionModifying built-in object prototypes

Requests to destinations not in allowedDomains (no-unauthorized-domain) cannot be allowed by relaxing a rule either. Add the destination to allowedDomains.

Using WebRTC​

Using RTCPeerConnection requires declaring no-rtc-connection. WebRTC reveals your IP address to the peer, so users are asked to consent to a "WebRTC connection" in the confirmation dialog before the item runs in an instance.

{
"item": {
"permissions": {
"allowedDomains": ["stun.l.google.com"],
"allowedCodeRules": ["no-rtc-connection"]
}
}
}
  • The hosts of the STUN / TURN servers in iceServers are checked against allowedDomains. The same applies to STUN / TURN servers a library uses by default, so list those hosts too
  • If you pass iceServers from a variable or an API response, the destinations cannot be verified, so you also need to declare no-network-without-permission