A-Frame Quickstart

{"id":10473,"library":"aframe","title":"A-Frame Web Framework for VR/AR","description":"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.","status":"active","version":"1.7.1","language":"javascript","source_language":"en","source_url":"https://github.com/aframevr/aframe","tags":["javascript","3d","aframe","cardboard","components","oculus","three","three.js","rift"],"install":[{"cmd":"npm install aframe","lang":"bash","label":"npm"},{"cmd":"yarn add aframe","lang":"bash","label":"yarn"},{"cmd":"pnpm add aframe","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","symbol":"Global AFRAME object via CDN","correct":"\n"},{"note":"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`.","wrong":"const AFRAME = require('aframe');","symbol":"A-Frame as an ES Module","correct":"import 'aframe';\n// Or if you need the AFRAME object for custom components:\nimport * as AFRAME from 'aframe';"},{"note":"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.","wrong":"import { registerComponent } from 'aframe'; // Incorrect named import for core functionality\nregisterComponent('my-component', { /* ... */ });","symbol":"Registering a custom component","correct":"AFRAME.registerComponent('my-component', {\n init: function () {\n console.log('My component initialized!');\n }\n});"}],"quickstart":{"code":"\n\n \n A-Frame Quickstart\n \n \n \n \n \n \n \n\n \n \n\n \n \n\n \n \n \n \n","lang":"html","description":"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."},"warnings":[{"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.","message":"A-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.","severity":"breaking","affected_versions":">=1.7.0"},{"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.","message":"A-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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"A-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.","severity":"breaking","affected_versions":">=1.2.0 <1.7.0"},{"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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0 <1.7.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the A-Frame script tag (``) is placed correctly in your HTML, preferably in the `` or at the beginning of ``, before any custom scripts that use `AFRAME`.","cause":"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.","error":"Uncaught ReferenceError: AFRAME is not defined"},{"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';`.","cause":"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.","error":"Failed to resolve module 'aframe' from ... (or similar bundler error)"},{"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.","cause":"The A-Frame library, which registers custom HTML elements like ``, has been loaded multiple times on the same page, or another script has inadvertently defined an element with the same tag.","error":"Custom element 'a-scene' has already been defined"}],"ecosystem":"npm"}