WebXR types aren't exported in 0.141

[CodyJasonBennett]

• three r141:
• node N/A:
• npm (or yarn) N/A:

Problem description:

Related: #223. Since r141, WebXR types are no longer exported alongside three and are now ambient. This is a breaking change that will cause projects' imported WebXR types to fail silently.

Relevant code:

// This
-import * as THREE from 'three'
-type Frame = THREE.XRFrame
// is now
+type Frame = XRFrame

Suggested solution:

Re-establish webxr/WebXR.d.ts, possibly re-export in addition to supporting ambient types (IDK how many people have migrated already, but best to minimize change).

[Methuselah96]

Are you saying that the old way is better than the new way, or just that it changed and change is bad? From my perspective it seems like making the WebXR types ambient is the way to go since they are similar to DOM or Node types in that they aren't imported from a package, they exist in the environment/context of the JS code.

[CodyJasonBennett]

It's a breaking change. Doesn't matter whether it's better in a vacuum -- it's our responsibility as library authors to ensure compatibility wherever possible, and this can cause nasty silent bugs in every package that depends on @types/three and uses WebXR features.

[Methuselah96]

How would you suggest going about making such a change? Surely breaking changes are inevitable and the three package itself makes breaking changes every release just like we do.

What are the bugs that this change causes? Does it not just cause compile errors because the types are no longer exported from the three types?

[CodyJasonBennett]

How would you suggest going about making such a change? Surely breaking changes are inevitable, and the three package itself makes breaking changes every release just like we do.

I wouldn't, not unless it was unavoidable. Ideally, this would be inline with changes made to three. This is not the case here, hence my inquiry.

What are the bugs that this change causes? Does it not just cause compile errors because the types are no longer exported from the three types?

To clarify, this would only be evident for user-facing code or users with skipLibCheck enabled. For those using libraries that depend on @types/three, WebXR types can silently fail to resolve as any if skipLibCheck is false. Otherwise, this would be a compiler error all the same.

[Methuselah96]

In what case would the WebXR types fail to resolve and thus silently fail? @types/three has a dependency on @types/webxr.

[CodyJasonBennett]

See the top issue comment, THREE.XRFrame would be an example. The focus of this issue is the usage of imported WebXR types in existing projects and libraries.

[Methuselah96]

Right, it's the silently failing part that I'm not understanding. Are you saying those types are in a declaration file that's never getting type-checked because skipLibCheck is enabled for both the author and consumer of the declaration file? If so, I don't see it as our problem to protect against type errors that happen because people writing declaration files aren't type-checking them before publishing them.

[CodyJasonBennett]

Please go back and read through this issue. This breaks existing code. I can make a PR, but it's confusing that I have to further justify the need. At this point, the conversation should be about damage control and what our options are. If the premise of the issue, which is that this could be done in a non-breaking way, is not true then we can close this issue.

[Methuselah96]

I understand it breaks existing code. We have different philosophies of breaking changes. In my opinion, three should not re-export WebXR types because it has no need to do so. We're solidly within SemVer to make this breaking change between 0.140.0 and 0.141.0 (even though types traditionally don't follow SemVer anyway).

[CodyJasonBennett]

Then you understand, while completely avoidable, this will require major semver in every library that depends on @types/three and uses its WebXR interfaces? This is strictly detrimental to the ecosystem.

[Methuselah96]

It depends, types and SemVer have always had a tenuous relationship. Can you give me an example library so I understand the practical problem holistically? I feel like it really depends on the details of how the library is using the WebXR types and what kind of dependency it has on @types/three that will determine whether it's a major SemVer change for the library.

[CodyJasonBennett]

It does not depend in this case, a hike of a peer dependency would be a breaking change (major semver). This is not something that can be worked around in user-land via @types/webxr without breaking compat since previous versions of @types/three vendored and exported their own WebXR definitions, which will cause a mismatch. However, if @types/three exported from @types/webxr, ambient types should match since r141. Ideally, this would be done in addition to #223.

If you need an example, I first noticed this when using https://github.com/pmndrs/react-three-fiber, which augments its RenderCallback in a WebXR session. I had been testing r141 and found that RenderCallback's WebXR args would resolve as any and lose type-safety. This is also the case of https://github.com/pmndrs/react-xr/tree/v3 (master is WIP), and every library that had imported WebXR types. I have to stress that this is not implementation-specific and merely with the usage of imported WebXR types, as per this issue.

[capnmidnight]

Three.js is not in control of the WebXR types. They don't ship changes to WebXR, they ship changes to their use of WebXR. Browser vendors ship changes to WebXR, thus the types need to be separate from Three.js.

A browser update could change the underlying APIs, but with the old way of exporting types defined in this package, there'd be no easy way of updating just the WebXR types. Typechecking would succeed, giving no indication that the underlying Three.js implementation was broken.

Additionally, @types/three exporting its own definition of WebXR types clashes with any use of @types/webxr that Three.js does not cover. In my own projects, I utilize some of the WebXRLayers features on the Oculus Quest. @types/three's WebXR types were not compatible with @types/webxr, requiring rather unsightly casts to any to get typechecking to pass. By utilizing @types/webxr as the single source of truth on WebXR types, implementing projects may use Three.js and extend into their own use of WebXR without as much trouble.

IIRC, the motivation for @three/types to export WebXR types was because @types/webxr was woefully out of date. That is no longer the case.

As for your concern about major dependency version bumping, pre-v1.0.0 packages should consider minor version changes to be major version changes. Three.js not excluded. If you're upgrading Three.js in your project (regardless of what @types/three does), you should be considering that a major change of your own project, too.

[CodyJasonBennett]

Three.js is not in control of the WebXR types. They don't ship changes to WebXR, they ship changes to their use of WebXR. Browser vendors ship changes to WebXR, thus the types need to be separate from Three.js.

You don't seem to understand the issue. Remember, @types/webxr is a dependency of @types/three (#218).

A browser update could change the underlying APIs, but with the old way of exporting types defined in this package, there'd be no easy way of updating just the WebXR types. Typechecking would succeed, giving no indication that the underlying Three.js implementation was broken.

This is simply untrue. You must be confused with vendored types which were exported. This is not the case if @types/webxr is exported. That's the whole appeal behind its inclusion in the first place, and these types can be shared with Babylonjs and other authors. Furthermore, @types/webxr can be used in other libraries' interfaces and have interop with three's. With the removal of these exports, type-checking will silently fail for every library on NPM which hadn't migrated over a major to r141, which I believe to be in error in the first place.

Additionally, @types/three exporting its own definition of WebXR types clashes with any use of @types/webxr that Three.js does not cover. In my own projects, I utilize some of the WebXRLayers features on the Oculus Quest. @types/three's WebXR types were not compatible with @types/webxr, requiring rather unsightly casts to any to get typechecking to pass. By utilizing @types/webxr as the single source of truth on WebXR types, implementing projects may use Three.js and extend into their own use of WebXR without as much trouble.

IIRC, the motivation for @three/types to export WebXR types was because @types/webxr was woefully out of date. That is no longer the case.

Again, see the above. @types/three uses @types/webxr and this should not change. Please read through this issue. Is there anything I can clarify about "breaking change" in respect to #223 and how this can be done in a non-breaking way?

As for your concern about major dependency version bumping, pre-v1.0.0 packages should consider minor version changes to be major version changes. Three.js not excluded. If you're upgrading Three.js in your project (regardless of what @types/three does), you should be considering that a major change of your own project, too.

I can hope that everyone is on the same page on how semver and software distribution works, but that is besides the point of this issue. There were no related code changes in three r141, only @types/three, and such was avoidable and IMO an oversight.

[capnmidnight]

.d.ts files are not real types. You can't really "vendor" them, in the same way that one might vendor an old DLL. They are shortcuts for the typechecker, built on a promise and a prayer. But they are not functionality. You have to trust that the @types package accurately reflects the library or API it claims to describe. If it doesn't, you won't find out until runtime. They help you make sure your code is consistent with the assumptions of those types, but they are fundamentally unsound.

So a library like Three.js doesn't ship a certain version of WebXR. It has to try to work with whatever version of WebXR is on the system. By originally vendoring @types/webxr, @types/three made the erroneous claim that Three.js used a certain WebXR API version. This is an impossible statement to make, and by ending the vendoring of @types/webxr, this becomes more clear.

It's not clear to me what the purpose would be of a types package that chose self-consistency over accuracy.

This is a trivial break. It's not like things were rearchitected and now the new API looks nothing like the old. We've corrected a major error in our type definitions, one that has nothing to do with the state of Three.js.

[CodyJasonBennett]

I'm not sure what this comment has to do with the above discussion. For the record, I greatly appreciate your herculean efforts in @types/webxr, and this has restored interop in a way that wasn't possible before. My suggestion at this point would be to export @types/webxr alongside @types/three in a patch release to mitigate a preventable catastrophic bubbling over NPM. By no means am I suggesting, nor is it feasible, to remove these types. The issue is as stated in the title, other issues should be tracked separately.

[capnmidnight]

A pull request would be helpful here in more ways than one

[joshuaellis]

So having read the thread (thank you all for maintaining a discussion about this) I do see both sides of the argument.

On the one hand, breaking changes are annoying and you can argue we should try to avoid them, the reality for a library like threejs and subsequently the types for said library, it's not exactly possible because of the approach the maintainers have taken on their own versioning scheme.

Secondly, imo threejs should never have shimmed their own webxr types, they should have updated them upstream and then used the type lib accordingly, mainly because it's not a library per say it's a web browser spec.

Which leads me to my next point, afaik no one else specifically exports a name-spaced version of a browser spec and we really should take the lead from the community on this one and not go against the flow...

I do sympathise with the "fail silently" but i'm struggling to reproduce this as it blatantly gives me an error in this codesandbox – https://codesandbox.io/s/async-wave-4eusoo?file=/src/App.tsx if you can provide an example of where it breaks silently it might help us understand the problem better. I don't think anyone is asking you to "justify" your requirements, it's about understanding the problem space correctly first before plowing into a solution we think is best as not to harm the core purpose of the library which is realistically to type threejs not navigator.

[CodyJasonBennett]

So having read the thread (thank you all for maintaining a discussion about this) I do see both sides of the argument.

On the one hand, breaking changes are annoying and you can argue we should try to avoid them, the reality for a library like threejs and subsequently the types for said library, it's not exactly possible because of the approach the maintainers have taken on their own versioning scheme.

Secondly, imo threejs should never have shimmed their own webxr types, they should have updated them upstream and then used the type lib accordingly, mainly because it's not a library per say it's a web browser spec.

Which leads me to my next point, afaik no one else specifically exports a name-spaced version of a browser spec and we really should take the lead from the community on this one and not go against the flow...

Same thoughts here, although I want to distinguish breaking changes from three-related code changes that are mirrored in @types/three and those initiated in @types/three. The former we have no agency to prevent and would ideally follow three's versioning. To re-iterate, I am bringing up concerns with compatibility with previous usage of exported or name-spaced types, as this should have come up earlier when adopting @types/webxr. Looking further into the related changes, I'm not sure if is possible to re-export these types for compat, as they're since ambient to play nice on other ambient types (see DefinitelyTyped/DefinitelyTyped#60331). Can someone clarify the behavior here? I believe this would rule out the possibility of a backward-compatible fix and confirm the need for a breaking change.

I do sympathise with the "fail silently" but i'm struggling to reproduce this as it blatantly gives me an error in this codesandbox – https://codesandbox.io/s/async-wave-4eusoo?file=/src/App.tsx if you can provide an example of where it breaks silently it might help us understand the problem better. I don't think anyone is asking you to "justify" your requirements, it's about understanding the problem space correctly first before plowing into a solution we think is best as not to harm the core purpose of the library which is realistically to type threejs not navigator.

I suppose this would be more specific to the usage of skipLibCheck, as this affects libraries published to NPM that were written before changes in r141. These would abstract user-authored code and break type-safety with failed resolutions to THREE.XR*. My earlier example of https://github.com/pmndrs/react-three-fiber may not be safe to run on Codesandbox (as it runs in a loop), but its useFrame hook would exercise use of WebXR types. This is defined as:

import * as THREE from 'three'

export type RenderCallback = (state: RootState, delta: number, frame?: THREE.XRFrame) => void

/**
 * Executes a callback before render in a shared frame loop.
 * Can order effects with render priority or manually render with a positive priority.
 * @see https://docs.pmnd.rs/react-three-fiber/api/hooks#useframe
 */
export function useFrame(callback: RenderCallback, renderPriority?: number): null

With usage being:

import { useFrame } from '@react-three/fiber'

useFrame((state, delta, frame) => {
  frame.foo()
})

frame is defined as frame?: THREE.XRFrame in RenderCallback, yet TS won't prompt you to null check here (since it's resolved to any). Is this perhaps a deeper issue of TypeScript (or more specifically skipLibCheck)? I'm not sure what resolve would look like for users/authors, but I hope this clarifies the issues I'm seeing.

Personally, I've hiked peer deps to prepare for a major in https://github.com/pmndrs/react-xr and https://github.com/pmndrs/react-three-fiber (aside from the big chain behind three-stdlib), but I worry that this is wrong of me to do (if there's a way for compat) or that this wouldn't be widely practiced (if a major is necessary). The correction is a bit awkward since it's only obvious to library authors or those who are immediate users of these types. In that case, we might want to note the need/steps for a migration in https://github.com/three-types/three-ts-types/releases/tag/r141.

[Methuselah96]

As I have mentioned previously, types and SemVer have a tenuous relationship. The types packages on DefinitelyTyped do not follow SemVer. Not only that, their dependencies on other types packages allow for any version (i.e., *) which is not correct from a SemVer perspective. Their philosophy is that only the latest version of everything is guaranteed to work correctly together. From that perspective, I don't think it's necessarily a requirement for react-three-fiber to make a major bump to use the ambient WebXR types since it doesn't even list any type of dependency on @types/three and because the npm community in general hasn't settled on the best way to handle breaking type changes as it relates to package versioning.

On top of that it's worth noting that react-three-fiber's current peer dependency on three@>=0.133 is incorrect if you're expecting that to also apply to @types/three since the react-three-fiber types reference THREE.CapsuleBufferGeometry which is not added until r139. In that sense, if you were actually trying to follow SemVer with react-three-fiber it would require much more frequent major bumps because it would require a major bump any time your types referenced a new type in @types/three.

If you are convinced that this breaking change requires libraries that have an implicit optional peer dependency on @types/three to make a major bump, then that's what you should do, I'm just noting that I think you're thinking about this more strictly than the way react-three-fiber has considered this in the past. If reat-three-fiber wanted to start seriously following SemVer, I would expect it to remove its open-ended peer dependency ranges, start testing against each new major version that comes out before adding it to the peer dependency range, add an optional peer dependency on @types/three with an established version range, and test each new change against every major version that it supports.

If you have any suggestions for how @types/three should go about making this breaking change easier to consume, then I'd love to hear them, but frankly I think your expectations about breaking changes as it relates to @types/three are unrealistic. The types will occasionally need to be able to make breaking changes that don't correspond to a breaking change in the underlying library even when it's technically avoidable when we believe it's the right path forward. How you decide to handle that in libraries that use @types/three is up to you, but it seems like the strictness of the stance that you're taking would require a lot more frequent major version bumps then what you're currently doing.

[CodyJasonBennett]

As I have mentioned previously, types and SemVer have a tenuous relationship. The types packages on DefinitelyTyped do not follow SemVer. Not only that, their dependencies on other types packages allow for any version (i.e., *) which is not correct from a SemVer perspective. Their philosophy is that (only the latest version of everything is guaranteed to work correctly together)[https://github.com/microsoft/DefinitelyTyped-tools/issues/433#issuecomment-1098329827]. From that perspective, I don't think it's necessarily a requirement for react-three-fiber to make a major bump to use the ambient WebXR types since it doesn't even list any type of dependency on @types/three and because the npm community in general hasn't settled on the best way to handle breaking type changes as it relates to package versioning.

Typesafety breaks in react-three-fiber if anything other than ambient types are used. How does this not warrant a major bump since r141 as its interfaces are consequently not compatible with older types? Is this something that was considered in such policy in DefinitelyTyped?

On top of that it's worth noting that react-three-fiber's current peer dependency on three@>=0.133 is incorrect if you're expecting that to also apply to @types/three since the react-three-fiber types reference THREE.CapsuleBufferGeometry which is not added until r139. In that sense, if you were actually trying to follow SemVer with react-three-fiber it would require much more frequent major bumps because it would require a major bump any time your types referenced a new type in @types/three.

Thanks for the thorough look, although this is a bit troubling. Is there a way to declare JSX interfaces and respect semver? I'm not sure if they can be declared dynamically, and semver becomes meaningless if majors are published in lockstep with three. react-three-fiber does not necessarily care about the version of three it's using, just the pieces that combine to create a scene-graph and any surrounding interfaces (e.g. useFrame), so it otherwise has great compatibility if not for the usage of types. This is something I'll have to look into more.

If you are convinced that this breaking change requires libraries that have an implicit optional peer dependency on @types/three to make a major bump, then that's what you should do, I'm just noting that I think you're thinking about this more strictly than the way react-three-fiber has considered this in the past. If react-three-fiber wanted to start seriously following SemVer, I would expect it to remove its open-ended peer dependency ranges, start testing against each new major version that comes out before adding it to the peer dependency range, add an optional peer dependency on @types/three with an established version range, and test each new change against every major version that it supports.

Rather than open-ended, do you mean having clear start and end versions? What would be a non implicit way to have @types/three as a dependency? This would only be for types, I don't recall react-three-fiber ever having a major bump related to three code, although I understand the peer deps must match.

If you have any suggestions for how @types/three should go about making this breaking change easier to consume, then I'd love to hear them, but frankly I think your expectations about breaking changes as it relates to @types/three are unrealistic. The types will occasionally need to be able to make breaking changes that don't correspond to a breaking change in the underlying library even when it's technically avoidable when we believe it's the right path forward. How you decide to handle that in libraries that use @types/three is up to you, but it seems like the strictness of the stance that you're taking would require a lot more frequent major version bumps then what you're currently doing.

FWIW, my suggestion would be to have this conversation about the need/options around a breaking change as it's being made. I don't understand what you mean in regards to policy on semver, I think you're reading too much into this issue beyond investigating a way for compat.

[Methuselah96]

Typesafety breaks in react-three-fiber if anything other than ambient types are used. How does this not warrant a major bump since r141 as its interfaces are consequently not compatible with older types? Is this something that was considered in such policy in DefinitelyTyped?

It doesn't warrant a major bump if you follow TypeScript/DefinitelyTyped's philosophy that types don't need to follow SemVer. My guess is that they have this philosophy because of situations like this. Trying to follow SemVer with types is much harder than following SemVer with JS. The other reason it might not warrant a major bump is because react-three-fiber doesn't even declare what versions of @types/three it's compatible with.

Thanks for the thorough look, although this is a bit troubling. Is there a way to declare JSX interfaces and respect semver? I'm not sure if they can be declared dynamically, and semver becomes meaningless if majors are published in lockstep with three. react-three-fiber does not necessarily care about the version of three it's using, just the pieces that combine to create a scene-graph and any surrounding interfaces (e.g. useFrame), so it otherwise has great compatibility if not for the usage of types. This is something I'll have to look into more.

You would have to make a major bump each time you referenced a type that was added in a more recent version. There is no way to dynamically load types. This is one of the reasons it's harder to follow SemVer for types than JS and why I think it would be impractical/unhelpful for react-three-fiber to try follow SemVer as it relates to its dependency on @types/three.

Rather than open-ended, do you mean having clear start and end versions? What would be a non implicit way to have @types/three as a dependency? This would only be for types, I don't recall react-three-fiber ever having a major bump related to three code, although I understand the peer deps must match.

Yes, a package that is trying to strictly follow SemVer should have a clear start and end version. Currently @types/three is not listed in the dependencies or peerDependencies of react-three-fiber. A non-implicit way to have @types/three as a dependency would be to list it in the peerDependencies (and make it optional).

To be clear, I'm not necessarily advocating that react-three-fiber should start adding end versions to all its ranges or explicitly list @types/three in its peerDependencies. I was just pointing out that these are ways that react-three-fiber is not following SemVer as strictly as it could.

FWIW, my suggestion would be to have this conversation about the need/options around a breaking change as it's being made. I don't understand what you mean in regards to policy on semver, I think you're reading too much into this issue beyond investigating a way for compat.

My struggle is that so far your main argument has been that we made a breaking change and we should not make breaking changes if it's avoidable. A direct result of this argument is that we would never, at any point be able to remove the export of the WebXR types because it would be a breaking change. I am fundamentally opposed to the concept that we would never be able to make a breaking change like this. Therefore I have no interest in discussing a backwards-compatible solution (if one is even possible) if this kind of breaking change would never be possible. If we did find a backwards-compatible solution, I would be strictly opposed to adopting it if it meant that we would never be able to remove the export of the WebXR types. Breaking changes need to be allowed from time to time and I still feel that your philosophy of breaking changes is unrealistic.

[CodyJasonBennett]

My struggle is that so far your main argument has been that we made a breaking change and we should not make breaking changes if it's avoidable. A direct result of this argument is that we would never, at any point be able to remove the export of the WebXR types because it would be a breaking change. I am fundamentally opposed to the concept that we would never be able to make a breaking change like this. Therefore I have no interest in discussing a backwards-compatible solution (if one is even possible) if this kind of breaking change would never be possible. If we did find a backwards-compatible solution, I would be strictly opposed to adopting it if it meant that we would never be able to remove the export of the WebXR types. Breaking changes need to be allowed from time to time and I still feel that your philosophy of breaking changes is unrealistic.

I have only suggested investigating a way for compat around the usage of ambient WebXR types if this was an unintentional breaking change. This is best explained in #232 (comment), which I seek clarification on. My initial mention of "restore WebXR.d.ts" referred to changes since and before #223, as it is unclear whether there was a point where @types/webxr were exported from WebXR.d.ts or used in a non-ambient way. If this is untrue or not something the project wants to investigate, we can safely close this issue as non-actionable. I do ask for the effects of this change to be considered, as this makes for a non-trivial migration or something worth mentioning in the release notes since it does not reflect code changes made in three.

[Methuselah96]

Thanks for the clarification, I was under the impression that you were against the change on the basis of it being a breaking change and not whether it was intentional or not. We effectively stopped exporting types from WebXR.d.ts in #218 when we first added the dependency on @types/webxr. That is because the only statement in that file was import '@types/webxr'; which (as far as I know) doesn't declare any exportable types, it's just adding ambient types, so the export * from './renderers/webxr/WebXR'; in Three.d.ts was not actually exporting anything.

The only discussion about the breaking nature of the change was #223 (comment) where I didn't think the effect of the change to be too burdensome for users, especially since it meant they were getting better WebXR types which I assumed would have its own subtle breaking changes whether it was exported from @types/three or not. I mistakenly said that users wouldn't have to change anything without considering that users would have to remove importing WebXR types from @types/three and instead use the ambient WebXR types, but I don't consider that to be overly burdensome since there's a good reason for the change. I had also not considered what this would mean for libraries that effectively have a peer dependency on @types/three because I didn't think libraries like react-three-fiber ever strictly paid attention to whether their types were compatible with old versions of @types/three and assumed they just took the stance of types packages that their types were only guaranteed to work with the latest version of @types/three (which seems reasonable to me).

I am happy to discuss whether we really want to make this breaking change if there is disagreement about that on the merits of the change itself and the changes it requires for libraries and users, but I believe it to be for the best. I have added this breaking change to the release notes.

[Methuselah96]

Gonna close this for now since we don't have any plans to change this, but we can always reopen it if people want to discuss it more.

[elalish]

So, I don't want to rehash this argument, but I'm hoping for some pointers. I got bit by this breaking change trying to update the three types in <model-viewer> because we had our own TS types for WebXR, but now they're conflicting with I guess the types you depend on? I tried removing mine (that would be great!), but it seems the official types aren't complete (for instance, they're missing domOverlay here: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/webxr/index.d.ts#L390). How should we go about patching these types, or is that no longer possible?

[Methuselah96]

You should make a PR to DefinitelyTyped with any missing types. Until that PR gets merged, you should be able to augment the interfaces with any missing properties (like this).

[elalish]

Thank you, that solved it!

[capnmidnight]

DOM Overlay is now in @types/webxr