To make the onboarding easier, we’ve added starter templates for both vanilla JS
npx @swc-uxp-wrappers/create-swc-uxp-ap <name-of-the-app>
cd <name-of-the-app>
and React JS
npx @swc-uxp-wrappers/create-swc-uxp-react-app <name-of-the-app>
cd <name-of-the-app>
A few pertinent questions that might arise:
Wait, I see these templates rely on packages under the scope @swc-uxp-wrappers. What are these?
The open-source Spectrum Web Components UI library targets a modern web browser. As you would be aware, UXP is not a browser (and never intends to be one either!), and with that comes limitations in supporting all the CSS properties and layouts that a modern browser supports. These wrappers are mostly the overrides of the styles to get these components to show up properly in a UXP environment. Don’t worry as your actual code need not use these wrappers directly. With some bundler configuration, the aliasing of the components is taken care of internally and you can just use regular code like
import '@spectrum-web-components/banner/sp-banner.js';
as one would while using the regular SWC components to consume them.
… And what about the @swc-react/* packages in the React template?
Well, these are the React wrappers developed by the open-source SWC team that enable consuming Spectrum Web Components in a React context.
I see a plethora of versions being used in the package.json of the starter template. Why aren’t you using the usual caret version (^) instead?
There are explicit versions of the underlying SWC components that the UXP team has locked onto to release this first batch of components as the later versions of these components had even more disparities concerning CSS etc. in the context of UXP. The team is working on moving to a more recent version of these components to help align with the current available SWC component versions. Using the ^ notation for specifying package dependencies is thus not possible since it would automatically bring in the latest package versions and lead to a break in the plugin UI.
OK but what about those sp-* elements that UXP has already been supporting until now?
Those are called Spectrum UXP Widgets and they aren’t going away anytime soon and in most cases can co-exist with SWC components with the obvious caveat that an sp-button imported from the SWC package can’t co-exist with the Spectrum UXP widget sp-button. Once any sp-* component is imported from the SWC package it supersedes the native Spectrum UXP widget. If you don’t import any sp-button but directly consume sp-button in either the HTML or in the JS code, you’ll get the natively supported Spectrum UXP button sp-button.
Why then should I go the route of using SWC and not using the existing Spectrum UXP widgets?
With simplicity comes the tradeoff that you hardly have any control over the native Spectrum UXP widget’s styling and they offer very limited APIs as opposed to SWC components. Think of the analogy of the standard <video> component on a browser. What if you’d like to inspect the elements in that Video element? You can’t. What if you wanted to extend from that Video element and override a few of its characteristics or behavior? You can’t! These limitations are pretty much similar to what you’d encounter with the native Spectrum UXP widgets which are essentially opaque elements. With SWC components, which are built atop Web Components, you can inspect the Shadow DOM of the component and if required, even extend from the SWC wrapper class to further customize the element as per your need. UXP comes with rich debugging support for Web Components.
When do we get to see more components in the list?
The UXP team is working on adding support for missing components and/or variants. Please stay tuned for further updates! Have more questions? Post on this forum!
If so, I won’t even try then. For now at least
