Defer initialization until end of aframe script or manual ready signal by mrxz · Pull Request #5481 · aframevr/aframe · GitHub

Description:
Updated and improved version of #5419. All <a-node> derived custom elements now wait for an aframeready event. This event is emitted near the end of the aframe bundle OR once the document.readyState becomes complete, whichever occurs last. In case the user needs to load more dependencies after this point, they can set the window.AFRAME_ASYNC flag and manually provide the ready signal using AFRAME.ready()

The following configurations are now all supported.

Classic script

<head>
    <script src="aframe-master.js"></script>
    <script src="components-and-systems.js"></script>
</head>

Deferred script (resolving #4038)

<head>
    <script src="aframe-master.js" defer></script>
    <script src="components-and-systems.js" defer></script>
</head>

(Async) Inline Module

<head>
    <script type="importmap">(...)</script>
    <script type="module" async> <!-- works with and without async -->
        import 'aframe';
        import 'components-and-systems';
    </script>
</head>

(Async) Module script file

<head>
    <script type="importmap">(...)</script>
    <script type="module" src="index.mjs" async></script> <!-- works with and without async -->
</head>

Inline Module (w/ dynamic imports) (original problem #5419, see updated glitch)

<head>
    <script type="importmap">(...)</script>
    <script type="module">
        window.AFRAME_ASYNC = true;
        await import("aframe")
        await import("components-and-systems");
        window.AFRAME.ready();
    </script>
</head>

You only really need to use AFRAME_ASYNC + AFRAME.ready() if the aframe main bundle is loaded after the document.readyState has already reached completed and you asynchronously register new components or systems. This means asynchronously compared to the aframe main bundle, so the following works:

import 'aframe';
AFRAME.registerComponent('new-component', { ... });

Whereas this would fail:

import 'aframe';
setTimeout(() => {
    AFRAME.registerComponent('new-component', { ... });
});

The way it fails is interesting in that it doesn't give errors and the components/system will work fine for the most part. But since they are registered after the scene has initialized, any attributes that weren't recognized as components or systems won't trigger component initialization. Effectively the runtime loading of components and systems could be improved. However, users should probably opt for AFRAME_ASYNC unless they know what they are doing, as cross component dependencies could still cause issues (say a library registers both foo and bar, where foo depends on bar, in which case initializing foo before bar is registered causes issues)

Changes proposed:

Let all <a-node> derived elements wait on aframeready event instead of readystatechanged
Emit aframeready once the main bundle is done or the document.readyState is complete (whichever comes last)
Introduce window.AFRAME_ASYNC flag to allow users to manually signal A-Frame that everything is ready (through AFRAME.ready())

ready is not a very descriptive word. Can we think of something better?

Perhaps readyState analogous to the document.readyState?

aframeReadyState?

As the local var name that works, though as file name I'd say readyState.js suffices as the aframe prefix won't make things clearer IMHO.

Any reason why this call has changed?

Yeah, the inheritance was a bit wonky. The doConnectedCallback function was essentially setup as a "virtual function" with subclasses overriding it and calling the base implementation (super.doConnectedCallback()), yet connectedCallback explicitly called the ANode implementation, forcing all subclasses to also override connectedCallback and replicating the same logic. From an OOP standpoint this didn't really make sense. Having one shared connectedCallback implementation is the cleanest solution IMO.

should be isDOMReady but not sure because isReady involves more than DOM now

Yeah, it now encompasses both DOM (= all elements are parsed) and A-Frame (everything registered, incl. third-party components/systems/etc...) being ready. Not sure what an apt name would be.

Perhaps the name could be changed to not reflect what needs to be ready, but that this action can take place. So something like canInitializeElements?

isAnodeReadyToLoad? too specific?

Feels a tad specific, but it also reads as if "Anode" is ready, instead of everything being ready "for Anode" to load. And we'd probably want to avoid using "load" here as the doConnectedCallback implementations do more than just invoke load.

We should add to docs and maybe README (if we can keep it simple) the different ways to load A-Frame listed in this PR description

How common would this pattern be? I don't have enough experience with modules

<head>
    <script type="importmap">(...)</script>
    <script type="module">
        window.AFRAME_ASYNC = true;
        await import("aframe")
        await import("components-and-systems");
        window.AFRAME.ready();
    </script>
</head>

Seems this PR makes A-Frame loading logic more complicated and harder to understand. Just making sure there's a good payoff.

@dmarcos This PR address more than just the dynamic imports. Without this PR none of the module based approaches work, nor classic scripts marked defer. Literally the only way to load A-Frame would be a blocking synchronous classic script. The dynamic import case in question only requires the emitReady method being exposed and the window.AFRAME_ASYNC condition in index.js.

While dynamic imports aren't the most common in my experience, #5419 raises a valid usage. On top of that more complex module setups (e.g. using top-level awaits) might also need window.AFRAME_ASYNC + emitReady despite not using dynamic imports.

Having this escape hatch is useful in those situations. Another option would be to treat module based imports differently by always requiring the user to manually signal everything is ready. That would eliminate the need for the magic AFRAME_ASYNC, but it would break any app out there that already got A-Frame working this way with their own workarounds (which, given the various issues on this subject over time, are probably more than a few).

Can we add some docs?

Co-authored-by: Chris Chua <chris.sirhc@gmail.com>

Can we add some docs?

Added an entry to the FAQ, let me know if that suffices. At first I thought adding it to either best-practices.md, or installation.md, but it just detracts from the focus of those articles. In general I would expect people either setting it up the "old traditional way", and for those in an ES module environment simply loading "aframe". In most cases that should now just work. When they do run into issue due to asynchronous loading of additional components/systems after loading A-Frame, there's now a point in the docs we can point them to.

Thanks!

mrxz force-pushed the async-loading branch from 326b766 to 329b523 Compare March 2, 2024 20:55

dmarcos reviewed Mar 6, 2024

View reviewed changes

Comment thread src/index.js Outdated

dmarcos reviewed Mar 6, 2024

View reviewed changes

dmarcos reviewed Mar 13, 2024

View reviewed changes

mrxz force-pushed the async-loading branch 2 times, most recently from a332055 to 9fb74d0 Compare March 14, 2024 10:01

dmarcos reviewed Mar 14, 2024

View reviewed changes

Comment thread src/index.js Outdated

Defer initialization until end of aframe script or manual ready signal

488ab1f

Co-authored-by: Chris Chua <chris.sirhc@gmail.com>

mrxz force-pushed the async-loading branch from 9fb74d0 to 488ab1f Compare March 15, 2024 10:09

dmarcos merged commit 4a89bb6 into aframevr:master Mar 15, 2024

vincentfretin mentioned this pull request Mar 27, 2024

Allow async loading of aframe library and interoperation with ES module libraries #5419

Closed

vincentfretin mentioned this pull request Sep 19, 2024

discussion: set renderer settings using javascript at instantiation? 3DStreet/3dstreet#872

Open

mrxz mentioned this pull request Jan 30, 2025

Initialization time of components is different between versions 1.5.0 and 1.6.0 #5649

Closed

vincentfretin mentioned this pull request Jun 21, 2026

[docs] Fix code snippet for AFRAME_ASYNC, need to call emitReady(), not ready() #5834

Merged

@@ @@ -1,5 +1,6 @@ @@
               /* global customElements, CustomEvent, HTMLElement, MutationObserver */
               var utils = require('../utils/');
+              var ready = require('./ready');

                   // Defer if DOM is not ready.
-                  if (document.readyState !== 'complete') {
-                    document.addEventListener('readystatechange', this.onReadyStateChange.bind(this));
+                  if (!ready.isReady) {

+                    document.addEventListener('aframeready', this.connectedCallback.bind(this));
                     return;
                   }
-                  ANode.prototype.doConnectedCallback.call(this);

Defer initialization until end of aframe script or manual ready signal by mrxz · Pull Request #5481 · aframevr/aframe · GitHub

Uh oh!

Uh oh!

Defer initialization until end of aframe script or manual ready signal - #5481

Defer initialization until end of aframe script or manual ready signal#5481dmarcos merged 1 commit intoaframevr:masteraframevr/aframe:masterfrom mrxz:async-loadingmrxz/aframe:async-loadingCopy head branch name to clipboard

Conversation

mrxz commented Feb 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmarcos commented Mar 13, 2024

Uh oh!

dmarcos commented Mar 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrxz commented Mar 14, 2024

Uh oh!

Uh oh!

dmarcos commented Mar 14, 2024

Uh oh!

mrxz commented Mar 15, 2024

Uh oh!

dmarcos commented Mar 15, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Defer initialization until end of aframe script or manual ready signal#5481
dmarcos merged 1 commit into
aframevr:masterfrom
mrxz:async-loading

mrxz commented Feb 28, 2024 •
edited
Loading

dmarcos commented Mar 13, 2024 •
edited
Loading