aframe

library0.1.0jsnpmunverified

A-Frame is an open-source web framework designed for building virtual reality (VR), augmented reality (AR), and general 3D experiences directly within a web browser using declarative HTML. It abstracts away the complexities of WebXR and Three.js, making 3D content creation accessible to a broader audience, including web developers, educators, and artists. The current stable version is 1.7.1, released in April 2025. A-Frame typically releases minor versions every few months, incorporating updates to its underlying Three.js dependency and adding new WebXR features. Key differentiators include its entity-component-system (ECS) architecture, which promotes reusability and modularity, and its focus on performance for interactive WebXR experiences. It supports various platforms, from mobile to desktop and dedicated VR/AR headsets compatible with WebXR.

web-framework

npm install aframe

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AFRAME

aframe

web-frameworkjavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Global AFRAME object via CDN

✓  <script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script>

This is the most common way to include A-Frame, making the `AFRAME` global object available. It's suitable for most web projects without complex build setups.

A-Frame as an ES Module

✓ import 'aframe'; // Or if you need the AFRAME object for custom components: import * as AFRAME from 'aframe';

✗ const AFRAME = require('aframe');

Since v1.7.0, A-Frame officially supports ES Modules. Direct `require()` is no longer supported for modern bundlers without CJS polyfills. When importing without `* as AFRAME`, it initializes A-Frame globally, making `AFRAME` available on `window`.

Registering a custom component

✓ AFRAME.registerComponent('my-component', { init: function () { console.log('My component initialized!'); } });

✗ import { registerComponent } from 'aframe'; // Incorrect named import for core functionality registerComponent('my-component', { /* ... */ });

Components, systems, and primitives are registered via methods on the global `AFRAME` object, regardless of how A-Frame itself is loaded (CDN or ESM). There are no direct named exports for these core registration functions from the main 'aframe' package.

This quickstart demonstrates a basic A-Frame scene with a camera, a ground, a sky, and a rotating box. It also includes a custom 'rotator' component defined in JavaScript and applied to the box, showcasing A-Frame's extensibility.

<!DOCTYPE html> <html> <head> <title>A-Frame Quickstart</title> <script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script> <script> // Register a custom component AFRAME.registerComponent('rotator', { schema: { speed: { type: 'number', default: 1000 } }, init: function () { this.el.setAttribute('animation', { property: 'rotation', to: '0 360 0', loop: true, dur: this.data.speed }); }, update: function () { this.el.setAttribute('animation', { property: 'rotation', to: '0 360 0', loop: true, dur: this.data.speed }); } }); </script> </head> <body> <a-scene background="color: #FAFAFA">  <a-entity camera look-controls wasd-controls position="0 1.6 0"></a-entity>  <a-box position="0 1 -3" rotation="0 45 0" color="#4CC3D9" rotator="speed: 2000"></a-box>  <a-plane position="0 0 -4" rotation="-90 0 0" width="10" height="10" color="#7BC8A4"></a-plane>  <a-sky color="#ECECEC"></a-sky> </a-scene> </body> </html>

Debug

Known issues

breakingA-Frame v1.7.0 replaced its internal CommonJS module system with ES Modules. Projects relying on `require('aframe')` or specific CommonJS imports for bundlers like Webpack 4 or older Node.js environments will break.

fix

Migrate your project to use ES Module `import` syntax. If using a bundler, ensure it is configured for ES Modules (e.g., Webpack 5+). Consider using import maps if targeting modern browsers directly.

affects: >=1.7.0

breakingA-Frame v1.4.0 migrated its underlying custom element implementation to Custom Elements V1. While largely backward compatible, projects with very specific custom element polyfills or those defining their own custom elements with conflicting naming conventions might experience issues.

fix

Ensure your browser or project environment fully supports Custom Elements V1. If you have custom element polyfills, update them to the latest versions. Avoid manually defining custom elements that conflict with A-Frame's `a-` prefixed elements.

affects: >=1.4.0

breakingA-Frame v1.2.0 updated its bundled Three.js version to r125, which deprecated `THREE.Geometry` in favor of `THREE.BufferGeometry`. Custom components or direct Three.js code that relied on `THREE.Geometry` will likely break.

fix

Update any custom A-Frame components or direct Three.js code to use `THREE.BufferGeometry` where applicable. Consult the Three.js migration guides for `r125` for detailed changes.

affects: >=1.2.0 <1.7.0

gotchaWhen integrating A-Frame with Next.js, versions prior to v1.7.1 could experience issues where A-Frame's default CSS styles were skipped or incorrectly applied, leading to visual glitches or missing UI elements like the 'Enter VR' button.

fix

Upgrade A-Frame to v1.7.1 or newer. If upgrading is not immediately possible, consider importing A-Frame's CSS explicitly in your Next.js project, potentially within `_app.js` or via a custom `_document.js`.

affects: >=1.0.0 <1.7.1

Errors

Common errors & fixes

Uncaught ReferenceError: AFRAME is not defined

A-Frame's main script file (aframe.min.js) has not been loaded or has loaded incorrectly before other scripts try to access the global AFRAME object.

fix

Ensure the A-Frame script tag (`<script src="https://unpkg.com/aframe/dist/aframe-master.min.js"></script>`) is placed correctly in your HTML, preferably in the `<head>` or at the beginning of `<body>`, before any custom scripts that use `AFRAME`.

Failed to resolve module 'aframe' from ... (or similar bundler error)

This error typically occurs in projects using bundlers (like Webpack, Rollup, Parcel) that expect ES Modules, but A-Frame was previously CJS or the bundler configuration is not set up to handle the v1.7.0 ESM transition.

fix

If on A-Frame v1.7.0+, update your bundler configuration to properly resolve ES Modules. Ensure your `package.json`'s `type` is set to `module` if it's a pure ESM project, or configure your bundler to handle 'aframe' as an ESM package. Consider using `import * as AFRAME from 'aframe';`.

Custom element 'a-scene' has already been defined

The A-Frame library, which registers custom HTML elements like `<a-scene>`, has been loaded multiple times on the same page, or another script has inadvertently defined an element with the same tag.

fix

Check your HTML to ensure the A-Frame script is only included once. If using a build system, verify that A-Frame is not being bundled and included multiple times. Avoid manually defining custom elements with `a-` prefixes if you are using A-Frame.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/aframevr/aframe ↗

packagehttps://www.npmjs.com/package/aframe ↗

homepagehttps://aframe.io ↗