Add JSX types for React (#1256)

* add JSX types for React et al * update changelog
2026-01-12 04:09:12 +00:00 · 2025-07-31 13:10:07 -04:00
parent b7a6ebd228
commit 89cf48c865
5 changed files with 83 additions and 11 deletions
--- a/package-lock.json
+++ b/package-lock.json
@@ -2983,6 +2983,12 @@
        "@types/node": "*"
      }
    },
+    "node_modules/@wc-toolkit/jsx-types": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@wc-toolkit/jsx-types/-/jsx-types-1.3.0.tgz",
+      "integrity": "sha512-2rcRyPNEAdesFlokSSFBuCjpPPrMySk4NqyVJsqCs/WczcAUnIGwjnJk2fd/SNmzSjxGFRIFLAhXOgFOHLPvxQ==",
+      "dev": true
+    },
    "node_modules/@web/browser-logs": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/@web/browser-logs/-/browser-logs-0.4.0.tgz",
@@ -13985,6 +13991,9 @@
        "qr-creator": "^1.0.0",
        "style-observer": "^0.0.7"
      },
+      "devDependencies": {
+        "@wc-toolkit/jsx-types": "^1.3.0"
+      },
      "engines": {
        "node": ">=14.17.0"
      }
--- a/packages/webawesome/custom-elements-manifest.js
+++ b/packages/webawesome/custom-elements-manifest.js
@@ -1,3 +1,4 @@
+import { jsxTypesPlugin } from '@wc-toolkit/jsx-types';
 import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
 import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
 // import { customElementVuejsPlugin } from 'custom-element-vuejs-integration';
@@ -164,6 +165,7 @@ export default {
      ],
    }),

+    // Generate custom JetBrains data
    customElementJetBrainsPlugin({
      outdir: './dist-cdn',
      excludeCss: true,
@@ -176,6 +178,12 @@ export default {
      },
    }),

+    // Generate JSX types (see https://wc-toolkit.com/integrations/jsx/)
+    jsxTypesPlugin({
+      fileName: 'custom-elements-jsx.d.ts',
+      outdir,
+    }),
+
    //
    // TODO - figure out why this broke when events were updated
    //
--- a/packages/webawesome/docs/docs/index.md
+++ b/packages/webawesome/docs/docs/index.md
@@ -22,6 +22,7 @@ To get everything included in Web Awesome, add the following code to the `<head>
 ```

 This snippet adds:
+
 - **Web Awesome styles**, a collection of stylesheets including essential default theme styles, optional [styles for native elements](/docs/utilities/native) and optional [utility classes](/docs/utilities)
 - **The autoloader**, a lightweight script watches the DOM for unregistered Web Awesome elements and lazy loads them for you — even if they're added dynamically

@@ -47,6 +48,7 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
 ---

 {# This looks weird, but without it, markdownItAttrs flags the raw calls incorrectly. #}
+
 <div>
 {%- raw -%}
  {% if currentUser.hasPro %}
@@ -57,7 +59,6 @@ Font Awesome users can set their kit code to unlock Font Awesome Pro icons. You
 {% endraw %}
 </div>

-
 ## Advanced Setup

 The autoloader is the easiest way to use Web Awesome, but different projects (or your own preferences!) may require different installation methods.
@@ -98,15 +99,15 @@ Web Awesome does not a provide a single import with all Web Awesome components.

 ```js
 // Option 1: import all Web Awesome styles
-import "@awesome.me/webawesome/dist/styles/webawesome.css"
+import '@awesome.me/webawesome/dist/styles/webawesome.css';

 // Option 2: import only the default theme
-import "@awesome.me/webawesome/dist/styles/themes/default.css"
+import '@awesome.me/webawesome/dist/styles/themes/default.css';

 // <wa-button>
-import "@awesome.me/webawesome/dist/components/button/button.js"
+import '@awesome.me/webawesome/dist/components/button/button.js';
 // <wa-input>
-import "@awesome.me/webawesome/dist/components/input/input.js"
+import '@awesome.me/webawesome/dist/components/input/input.js';
 ```

 Once they've been imported, you can use them in your HTML normally. Component imports are located in the "Importing" section of each component's documentation.
@@ -148,13 +149,63 @@ Most of the magic behind assets is handled internally by Web Awesome, but if you
 </script>
 ```

-## The difference between `/dist` and `/dist-cdn`
+### The Difference Between `/dist` & `/dist-cdn`

-If you have Web Awesome installed locally via NPM, you'll notice 2 directories. `/dist-cdn` and `/cdn`.
+If you have Web Awesome installed locally via npm, you'll notice the following directories in the project's root:

-The `/dist-cdn` files are bundled differently than the `/dist` files. The `/dist-cdn` files come pre-bundled, which means all dependencies are "inlined" so there are no "bare" references like `import "lit"`. The `/dist` files **DO NOT** come pre-bundled, allowing your bundler of choice to more efficiently de-duplicate dependencies, resulting in smaller bundles and optimal code sharing.
+```
+dist/
+dist-cdn/
+```

-TLDR:
+The `dist-cdn` files come with everything bundled together, so you can use them directly without a build tool. The dist files keep dependencies separate, which lets your bundler optimize and share code more efficiently.

- `@awesome.me/webawesome/dist-cdn` is for CDNs or people not using a bundler.
- `@awesome.me/webawesome/dist` is for bundlers or importmaps.
+Use `dist-cdn` if you're loading directly in the browser or from a CDN. Use `dist` if you're using a bundler like Webpack or Vite.
+
+## React Users
+
+React 19+ [supports custom elements](https://react.dev/blog/2024/04/25/react-19#support-for-custom-elements), so you can import them and use them as you'd expect. Just make sure you've included your Web Awesome theme into your app first.
+
+```jsx
+import '@awesome.me/webawesome/dist/components/button/button.js';
+
+function App() {
+  return <wa-button variant="brand">Button</wa-button>;
+}
+
+export default App;
+```
+
+If you're using TypeScript, you can add type safety using the types file located at:
+
+```
+node_modules/@awesome.me/webawesome/dist/custom-elements-jsx.d.ts
+```
+
+This gives you inline documentation, autocomplete, and type-safe validation for every component. You can add the types to your project by updating your `tsconfig.json` file as shown below.
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node-modules/@awesome.me/webawesome/dist/custom-elements-jsx.d.ts"]
+  }
+}
+```
+
+Another way is to create a declaration file and extend JSX's `IntrinsicElements`:
+
+```ts
+import type { CustomElements, CustomCssProperties } from '@awesome.me/webawesome/dist/custom-elements-jsx.d.ts';
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends CustomElements {}
+  }
+  interface CSSProperties extends CustomCssProperties {}
+}
+```
+
+:::details React 18 and below
+React 18 and below have [poor support](https://custom-elements-everywhere.com/#react) for custom elements. For legacy versions of React, we provide React wrappers for every component. You can find the import instructions by selecting the _React_ tab from the _Importing_ section of each
+component's documentation.
+:::
--- a/packages/webawesome/docs/docs/resources/changelog.md
+++ b/packages/webawesome/docs/docs/resources/changelog.md
@@ -16,6 +16,7 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
 - Added the `animating` custom state to `<wa-details>` [pr:1214]
 - Added `--wa-tooltip-border-color`, `--wa-tooltip-border-style`, and `--wa-tooltip-border-width` tokens [issue:1224]
 - Added the `without-arrow` attribute to `<wa-popover>` and `<wa-tooltip>` to hide arrows without artifacts
+- Added JSX types for use with React and others [pr:1256]

 ### Bug Fixes and Improvements {data-no-outline}

--- a/packages/webawesome/package.json
+++ b/packages/webawesome/package.json
@@ -86,5 +86,8 @@
    "*.{ts,js}": [
      "prettier --write"
    ]
+  },
+  "devDependencies": {
+    "@wc-toolkit/jsx-types": "^1.3.0"
  }
 }