Amplify CLI XR Plugin

3.4.4 verified Thu Apr 23 auth: no javascript deprecated

The `amplify-category-xr` package, currently at version `3.4.4` as per the provided metadata, extends the AWS Amplify Command Line Interface (CLI) to allow developers to provision and manage cloud resources for Extended Reality (XR) applications. This typically included services for AR/VR/MR capabilities within Amplify-powered backends. As part of the broader AWS Amplify CLI monorepo, its release cadence historically aligned with frequent updates for bug fixes and minor features across the CLI. However, this plugin's core functionality is now deprecated as its underlying dependency, Amazon Sumerian, is no longer accepting new customers, and existing Sumerian scenes were slated to be unavailable after February 21, 2023. Therefore, while the CLI plugin exists, it no longer provisions functional resources. Its original key differentiator was abstracting complex AWS service configurations for XR, integrating with other Amplify categories like Auth and Storage.

Common errors

error Command 'xr' not found ↓

cause The `@aws-amplify/cli` is either not installed, or the `amplify-category-xr` plugin itself might be missing or corrupted within the CLI installation.

fix

Ensure @aws-amplify/cli is installed globally (npm install -g @aws-amplify/cli). If the issue persists, try reinstalling the CLI. Note that even if the command is found, it's deprecated.

error Error: User is not authorized to perform: sumerian:CreateScene on resource: arn:aws:sumerian:... ↓

cause The configured AWS IAM user lacks the necessary permissions to interact with Amazon Sumerian or other XR-related AWS services.

fix

Update the IAM policy attached to the AWS user configured with Amplify CLI to include permissions for Amazon Sumerian and any other related services (e.g., S3 for asset storage). However, consider the service's deprecation before investing in permission setup.

error ResourceNotFoundException: The requested scene could not be found. ↓

cause This typically means an XR resource was referenced but was either not deployed correctly with `amplify push`, or was previously removed from the cloud, or the underlying Amazon Sumerian service itself has removed the scene due to its deprecation.

fix

Verify that amplify push was run successfully. Given the deprecation of Amazon Sumerian, this error is now the expected behavior for any XR resource.

Warnings

breaking The AWS Amplify XR features, and by extension this CLI plugin, are deprecated. The underlying Amazon Sumerian service stopped accepting new customers, and existing customer scenes became unavailable after February 21, 2023. Attempting to use `amplify xr` commands will no longer provision functional XR resources. ↓

fix Migrate away from Amplify XR features. AWS recommends exploring alternative solutions for AR/VR/MR applications, as Amplify no longer provides direct support for this category via Sumerian.

gotcha Ignoring `amplify push` after making local configuration changes for any Amplify category will result in your cloud environment not reflecting the desired state. This is fundamental to Amplify CLI usage. ↓

fix Always run `amplify push` after `amplify add`, `amplify update`, or `amplify remove` to synchronize your local backend definition with your AWS cloud resources.

gotcha Ensure your AWS credentials and region are correctly configured using `amplify configure`. Inconsistent or incorrect region settings, or insufficient IAM permissions for the AWS account, can lead to deployment failures or inaccessible resources. ↓

fix Run `amplify configure` to set up or verify your AWS credentials and default region. Ensure the IAM user has appropriate permissions for all AWS services Amplify provisions.

Install

npm install amplify-category-xr

yarn add amplify-category-xr

pnpm add amplify-category-xr

Imports

amplify xr add
wrong
```
import { add } from 'amplify-category-xr'
```
correct
```
amplify xr add
```
This package is a CLI plugin. Its functionality is exposed via command-line interface commands, not through direct JavaScript/TypeScript imports into application code. While the command exists, it no longer provisions functional XR resources due to service deprecation.
amplify xr update
wrong
```
import { updateXr } from 'amplify-category-xr'
```
correct
```
amplify xr update
```
Interaction is exclusively through CLI commands. Direct programmatic import of this plugin is not the intended use case, and the command itself is impacted by underlying service deprecation.
amplify xr push
wrong
```
require('amplify-category-xr').push()
```
correct
```
amplify xr push
```
The 'push' command deploys local Amplify XR configurations to the cloud. Like other XR commands, its practical utility is nullified by the deprecation of Amazon Sumerian.

Quickstart

Demonstrates the CLI workflow for adding and deploying an XR resource, despite its functional deprecation.

# Ensure Amplify CLI is installed globally
npm install -g @aws-amplify/cli

# Initialize a new Amplify project (if not already done)
amplify init

# Attempt to add an XR resource (will prompt for details)
# Note: This command will no longer provision functional resources due to underlying service deprecation.
amplify xr add

# Follow the CLI prompts, e.g., choosing a scene name and initial assets.

# Push the changes to deploy the (now non-functional) XR resources to the cloud
amplify push --yes