shinkom 1.2.1 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +7 -7
- package/README.md +383 -383
- package/dist/bundles/core/elements/recent-result-item.js +1 -1
- package/dist/bundles/core/elements/results-history-item.js +1 -1
- package/dist/bundles/core/elements/templates/compat-view.templates.js +1 -1
- package/dist/bundles/core/elements/templates/control-panel.templates.js +1 -1
- package/dist/bundles/core/elements/templates/root-styles.template.js +1 -1
- package/dist/bundles/core/helpers.js +1 -1
- package/dist/bundles/engine/index.js +1 -1
- package/dist/bundles/gen/browser-data.js +1 -1
- package/dist/bundles/gen/browser-usage-data.js +1 -1
- package/dist/bundles/gen/compat-data.js +1 -1
- package/dist/bundles/pkg/shinkore.d.ts +7 -17
- package/dist/bundles/pkg/shinkore_bg.wasm +0 -0
- package/dist/bundles/types/public.d.ts +56 -56
- package/dist/bundles/types/types.d.ts +98 -98
- package/dist/bundles/ui/compat-ui/index.js +1 -1
- package/dist/bundles/ui/compatibility-view/index.js +1 -1
- package/dist/bundles/ui/control-panel/index.js +1 -1
- package/dist/bundles/ui/inspector/index.js +1 -1
- package/dist/modules/gen/browser-data.cjs +1 -1
- package/dist/modules/gen/browser-usage-data.cjs +1 -1
- package/dist/modules/gen/compat-data.cjs +1 -1
- package/dist/modules/pkg/shinkore_bg.wasm +0 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,383 +1,383 @@
|
|
|
1
|
-
<h1 align="center">Shinkom</h1>
|
|
2
|
-
|
|
3
|
-
<p align="center">
|
|
4
|
-
<strong><em><span style="font-style:italic;">Shinkom</span></em>, the high-speed rail for real-time cross-browser compatibility analysis for websites.<br>
|
|
5
|
-
A JavaScript library powered by a Rust/WASM engine, providing native speed cross-browser compatibility data processing and analysis.<br>
|
|
6
|
-
</strong>
|
|
7
|
-
</p>
|
|
8
|
-
<div align="center">
|
|
9
|
-
<img width="500" height="500" alt="shinkom-logo" src="https://github.com/user-attachments/assets/54e9aa80-3a85-44d5-9d7f-9266303eb156" />
|
|
10
|
-
</div>
|
|
11
|
-
|
|
12
|
-
## Introduction
|
|
13
|
-
|
|
14
|
-
**Shinkom** is a JavaScript library for real-time website cross-browser compatibility analysis.
|
|
15
|
-
|
|
16
|
-
It is *compatible* with many popular libraries and frameworks such as **React, Vue, NextJs, Nuxt** and Vanilla JS.
|
|
17
|
-
It is also accessible in **Node.Js**, [see more on Node.Js usage here](#nodejs).
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Purpose
|
|
22
|
-
|
|
23
|
-
The web has evolved a lot and so have browsers. Among the most popular browsers such as **Chrome, Firefox, Edge, Safari, Opera** and the like,
|
|
24
|
-
there are always new browsers being developed aiming to push the boundaries of what is capable of existing browser technology.
|
|
25
|
-
However, this causes a discrepency in the feature-set between modern browsers since they may use differing technology and architecture
|
|
26
|
-
when developing new browsers.
|
|
27
|
-
Web technology and languages such as **HTML, CSS and JavaScript** are constantly evolving which aids in the problem of features
|
|
28
|
-
either being widely supported or having limited support between browsers.
|
|
29
|
-
|
|
30
|
-
This makes cross-browser compatibility all the more important for a web developer to consider as neglecting this could lead
|
|
31
|
-
to users on other browsers having a poor experience visiting a website due to broken layouts, styling or functionality.
|
|
32
|
-
However, testing for compatibility on different browsers can often become tedious due to the volume of different browsers
|
|
33
|
-
and the many versions of each single one.
|
|
34
|
-
|
|
35
|
-
This is where **Shinkom** connects the rails!
|
|
36
|
-
|
|
37
|
-
The purpose of this library is to provide web developers an intuitive library for analysing the compatibility of a website in real-time during development.
|
|
38
|
-
This project depends heavily on the [@mdn/browser-compat-data](https://github.com/mdn/browser-compat-data/tree/main) project by MDN, which stores a large amount of compatibility data about
|
|
39
|
-
browsers and web features.
|
|
40
|
-
|
|
41
|
-
Most online browser compatibility websites usually require payment for the use of their services and don't often allow for
|
|
42
|
-
finer control of what specifically to test within the website.
|
|
43
|
-
Shinkom aims to provide that fine level of control, to allow web developers to discover the compatibility of their components
|
|
44
|
-
across many browsers during development.
|
|
45
|
-
|
|
46
|
-
This library can also make it easier to identify which specific browsers to test immediately without having to sift through documentation
|
|
47
|
-
to check if a feature works on a particular browser or test the website on every browser to discover potential issues.
|
|
48
|
-
|
|
49
|
-
**Shinkom conducts the analysis of the website content and browser compatibility data and delivers the compatibility result as fast as a bullet train.**
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## IMPORTANT
|
|
54
|
-
|
|
55
|
-
### WebAssembly
|
|
56
|
-
|
|
57
|
-
It is important to mention that this project is made with **WebAssembly** through [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen).
|
|
58
|
-
Therefore, the engine will need to be initialized asynchronously and your server will need to accept the `application/wasm` MIME type.
|
|
59
|
-
It is recommended to read relevant documentation in whichever framework or bundler you are using to apply the correct configuration to accept
|
|
60
|
-
WASM files on your server or visit the [examples](/examples) directory, if your framework or bundler of choice is listed there for a working example.
|
|
61
|
-
|
|
62
|
-
### Server-side Rendering Applications
|
|
63
|
-
|
|
64
|
-
The core engine of Shinkom can be run in Node.js environments, but this is not true for the UI components and the Shinkom entry-point as they are browser-only.
|
|
65
|
-
If using a framework that uses SSR, make sure to initialize the library in hooks that perform side-effects (i.e. `useEffect` or `onMounted`) to prevent
|
|
66
|
-
`window is undefined` errors during SSR pre-rendering.
|
|
67
|
-
|
|
68
|
-
---
|
|
69
|
-
|
|
70
|
-
## Getting Started
|
|
71
|
-
|
|
72
|
-
Shinkom can be installed from npm via the `shinkom` package
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
npm install -D shinkom
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
Once installed, you can then import the Shinkom package in JavaScript.
|
|
79
|
-
Shinkom can be used in frontend frameworks, bundlers and vanilla JS.
|
|
80
|
-
|
|
81
|
-
### Vanilla JS
|
|
82
|
-
|
|
83
|
-
```javascript
|
|
84
|
-
import { Shinkom } from 'shinkom'
|
|
85
|
-
|
|
86
|
-
const shinkom = new Shinkom()
|
|
87
|
-
|
|
88
|
-
shinkom.init()
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
### React
|
|
92
|
-
|
|
93
|
-
```javascript
|
|
94
|
-
import React, { useEffect } from 'react'
|
|
95
|
-
import { Shinkom } from 'shinkom'
|
|
96
|
-
|
|
97
|
-
export default function App() {
|
|
98
|
-
useEffect(() => {
|
|
99
|
-
const shinkom = new Shinkom()
|
|
100
|
-
|
|
101
|
-
shinkom.init()
|
|
102
|
-
|
|
103
|
-
return () => shinkom.destroy()
|
|
104
|
-
}, [])
|
|
105
|
-
}
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
### Vue
|
|
109
|
-
|
|
110
|
-
```javascript
|
|
111
|
-
<script setup lang="ts">
|
|
112
|
-
import { onMounted, onUnmounted } from 'vue'
|
|
113
|
-
import { Shinkom } from 'shinkom'
|
|
114
|
-
import wasm from 'shinkom/wasm?url'
|
|
115
|
-
|
|
116
|
-
const shinkom = new Shinkom({
|
|
117
|
-
engine: {
|
|
118
|
-
wasmURL: wasm
|
|
119
|
-
}
|
|
120
|
-
})
|
|
121
|
-
|
|
122
|
-
onMounted(() => {
|
|
123
|
-
shinkom.init()
|
|
124
|
-
})
|
|
125
|
-
|
|
126
|
-
onUnmounted(() => {
|
|
127
|
-
shinkom.destroy()
|
|
128
|
-
})
|
|
129
|
-
</script>
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
You can also use Shinkom through the `require` statement in commonJS.
|
|
133
|
-
|
|
134
|
-
```javascript
|
|
135
|
-
const Shinkom = require('shinkom').Shinkom
|
|
136
|
-
|
|
137
|
-
const shinkom = new Shinkom()
|
|
138
|
-
|
|
139
|
-
shinkom.init()
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
If there are other frameworks or bundlers not listed here as being supported that you would like to use Shinkom with,
|
|
143
|
-
then consider contributing by creating a **pull request** on the **dev** branch to support it and make sure to **create an example for others!**
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
## Usage
|
|
148
|
-
|
|
149
|
-
### Basic
|
|
150
|
-
|
|
151
|
-
The simplest and **recommended** way to utilize Shinkom is through the main entry-point.
|
|
152
|
-
|
|
153
|
-
```javascript
|
|
154
|
-
import { Shinkom } from 'shinkom'
|
|
155
|
-
|
|
156
|
-
const shinkom = new Shinkom()
|
|
157
|
-
|
|
158
|
-
shinkom.init()
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
This enables the use of the **interactive UI and Rust/WASM engine** in order to inspect elements on a page.
|
|
162
|
-
|
|
163
|
-
### Modular
|
|
164
|
-
|
|
165
|
-
Shinkom was made to be **modular**, meaning you can also choose to use individual modules that you would
|
|
166
|
-
like to make use of for finer control.
|
|
167
|
-
|
|
168
|
-
```javascript
|
|
169
|
-
import { ShinkomBus, ShinkomState, SKEngine, CompatInspector, CompatUI } from 'shinkom'
|
|
170
|
-
|
|
171
|
-
const bus = new ShinkomBus()
|
|
172
|
-
const state = new ShinkomState()
|
|
173
|
-
const engine = new SKEngine(bus)
|
|
174
|
-
const inspector = new CompatInspector(bus, state)
|
|
175
|
-
const ui = new CompatUI(bus, state, [inspector])
|
|
176
|
-
|
|
177
|
-
ui.init()
|
|
178
|
-
engine.initEngine()
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
### Engine
|
|
182
|
-
|
|
183
|
-
The **Rust/WASM engine** can be used separately from the UI components in cases where you may want to automate
|
|
184
|
-
compatibility inspection without manually having to interact with a page.
|
|
185
|
-
|
|
186
|
-
```javascript
|
|
187
|
-
import { SKEngine } from 'shinkom/engine'
|
|
188
|
-
|
|
189
|
-
const engine = new SKEngine()
|
|
190
|
-
|
|
191
|
-
const run = async () => {
|
|
192
|
-
await engine.initEngine()
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
await run()
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
If needed, you can also **preload** the WASM file for **lazy initialization** of the engine,
|
|
199
|
-
this can be particularly useful when using the engine in **SSR applications** to eliminate
|
|
200
|
-
constant cold starts.
|
|
201
|
-
|
|
202
|
-
```javascript
|
|
203
|
-
import { SKEngine } from 'shinkom/engine'
|
|
204
|
-
|
|
205
|
-
const engine = new SKEngine()
|
|
206
|
-
|
|
207
|
-
const preLoad = async () => {
|
|
208
|
-
await engine.loadWasm()
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
await preLoad()
|
|
212
|
-
|
|
213
|
-
// other operations //
|
|
214
|
-
|
|
215
|
-
await engine.initEngine()
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
---
|
|
219
|
-
|
|
220
|
-
## Compatibility Checks
|
|
221
|
-
|
|
222
|
-
### Schema
|
|
223
|
-
|
|
224
|
-
In order to discover potential compatibility issues, Shinkom implements a score metric for the result of the compatibility check.
|
|
225
|
-
|
|
226
|
-
The general schema that an average compatibility check will follow goes like this:
|
|
227
|
-
|
|
228
|
-
```javascript
|
|
229
|
-
{
|
|
230
|
-
"lookup_results": [
|
|
231
|
-
// results for each web feature
|
|
232
|
-
{
|
|
233
|
-
"name": "fake-element", // name of the web feature
|
|
234
|
-
"mdn_url": "https://developer.mozilla.org/docs/web/HTML/Reference/Elements/fake-element", // link that leads to MDN documentation of the web feature
|
|
235
|
-
"compat_score": "100.00", // score based on the sum of the browser_score and status_score over the max compat score
|
|
236
|
-
"browser_score": "100.00", // score based on the sum of weighted scores in each browser
|
|
237
|
-
"status_score": "100.00", // score based on the status object in compatibility data
|
|
238
|
-
"browsers": [
|
|
239
|
-
// results for each checked browser
|
|
240
|
-
{
|
|
241
|
-
"browser_name": "edge", // name of the browser
|
|
242
|
-
"score": {
|
|
243
|
-
"raw_score": "100.00", // score based on the safety of feature in browser
|
|
244
|
-
"weighted_score": "5.74", // score based on the usage of edge over the total market share between checked browsers
|
|
245
|
-
},
|
|
246
|
-
"versions": {
|
|
247
|
-
"version_added": "34" // feature added in edge engine version 34
|
|
248
|
-
}
|
|
249
|
-
}
|
|
250
|
-
]
|
|
251
|
-
}
|
|
252
|
-
],
|
|
253
|
-
// the overall score of the compatibility check
|
|
254
|
-
"overall_score": 100
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
This object consists of the following:
|
|
259
|
-
|
|
260
|
-
- The `overall_score` property is a number that represents the final score of the compatibility check. It is a sum of each `compat_score` a
|
|
261
|
-
web feature has been given.
|
|
262
|
-
- The `lookup_results` property is an array of objects that contains each web feature's individual compatibility results.
|
|
263
|
-
- The `name` property is a string representing the name of the web feature.
|
|
264
|
-
- The `mdn_url` property is a string containing a link to the MDN Web Docs documentation for the web feature.
|
|
265
|
-
- The `compat_score` property is a string representing the calculated score for the web feature. It is calculated by summing the `browser_score` and `status_score`
|
|
266
|
-
and then dividing that sum by the total compatibility score a feature can get (currently 200).
|
|
267
|
-
- The `browser_score` property is a string representing the sum of the `weighted_score`'s between each browser for the web feature.
|
|
268
|
-
- The `status_score` property is a string representing the calculated score based on the current status of this web feature (standard_track, experimental, or deprecated).
|
|
269
|
-
- The `browsers` property is an array of objects that contains each browsers individual compatibility results.
|
|
270
|
-
- The `browser_name` property is a string representing the name of the checked browser.
|
|
271
|
-
- The `score` property is an object containing the `raw_score` and `weighted_score` for the web feature in a particular browser.
|
|
272
|
-
- `raw_score` is the calculated score before weighting is applied, which can be interpreted as the *safety* of a web feature.
|
|
273
|
-
- `weighted_score` is the raw score but with a weighting multiplier calculated as such: **total_browser_usage / market_share**.
|
|
274
|
-
- The `versions` property can be either an object or an array of objects depending on whether the web feature has been added, removed or partially implemented
|
|
275
|
-
in many different versions or just one version.
|
|
276
|
-
|
|
277
|
-
### Scoring
|
|
278
|
-
|
|
279
|
-
The scoring for the compatibility check is an important feature to make sure that it gives fair and understandable results that won't leave you
|
|
280
|
-
guessing why a check resulted in a particular score.
|
|
281
|
-
|
|
282
|
-
The table below lists the score types and their respective formulas:
|
|
283
|
-
|
|
284
|
-
| Score Type | Formula |
|
|
285
|
-
|----------------|:-------------------------------------------------------------------------------------------:|
|
|
286
|
-
| overall_score | (compat_score~1~ + compat_score~2~ + ... compat_score~n~) / N |
|
|
287
|
-
| compat_score | ((browser_score + status_score) / MAX_COMPAT_SCORE) * 100 |
|
|
288
|
-
| browser_score | ((weighted_score~1~ + weighted_score~2~ + ... weighted_score~n~) / MAX_BROWSER_SCORE) * 100 |
|
|
289
|
-
| status_score | (status_score / MAX_STATUS_SCORE) * 100 |
|
|
290
|
-
| raw_score | Raw score calculation explained below |
|
|
291
|
-
| weighted_score | raw_score * (total_usage / market_share) |
|
|
292
|
-
|
|
293
|
-
Here are a few things to clarify about these formulas:
|
|
294
|
-
|
|
295
|
-
- In `overall_score`, *N* represents the number of lookup results returned.
|
|
296
|
-
- `MAX_COMPAT_SCORE` has a value of 200, whereas `MAX_BROWSER_SCORE` and `MAX_STATUS_SCORE` have a value of 100.
|
|
297
|
-
- The `raw_score` is calculated based on many different factors.
|
|
298
|
-
- If the current version of the browser is greater than the `version_added` value, the score is 100. This is
|
|
299
|
-
also the case if `version_added` is set to `true`.
|
|
300
|
-
- If the `version_removed` value is greater than the `version_added` value, the score is 0 since it is a removed feature.
|
|
301
|
-
- If the `partial_implementation` value is set to true, the score is 80.
|
|
302
|
-
- `total_usage` is the usage of a browser across all of its versions, and the `market_share` is the sum of `total_usage`
|
|
303
|
-
between every browser.
|
|
304
|
-
- The `browser_score` is the sum of the weighted scores from each browser divided by the `MAX_BROWSER_SCORE`.
|
|
305
|
-
|
|
306
|
-
---
|
|
307
|
-
|
|
308
|
-
## Node.js
|
|
309
|
-
|
|
310
|
-
Shinkom can be utilised in Node environments through its Engine module.
|
|
311
|
-
The UI components are strictly for browser environments, however the engine itself can be used independently in both environments.
|
|
312
|
-
|
|
313
|
-
### ESM Bundles
|
|
314
|
-
|
|
315
|
-
```javascript
|
|
316
|
-
import { SKEngine } from 'shinkom/engine'
|
|
317
|
-
|
|
318
|
-
const skEngine = new SKEngine()
|
|
319
|
-
|
|
320
|
-
await skEngine.initEngine()
|
|
321
|
-
|
|
322
|
-
skEngine.checkElement(`<div id="test-div" class="test-classes">Test Div</div>`)
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
### CommonJS Modules
|
|
326
|
-
|
|
327
|
-
```javascript
|
|
328
|
-
const SKEngine = require('shinkom/engine').SKEngine
|
|
329
|
-
|
|
330
|
-
const skEngine = new SKEngine()
|
|
331
|
-
|
|
332
|
-
const run = async () => {
|
|
333
|
-
await skEngine.initEngine()
|
|
334
|
-
|
|
335
|
-
skEngine.checkElement(`<div id="test-div" class="test-classes">Test Div</div>`)
|
|
336
|
-
}
|
|
337
|
-
|
|
338
|
-
run()
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
---
|
|
342
|
-
|
|
343
|
-
## Development Scripts
|
|
344
|
-
|
|
345
|
-
When cloning or forking this library, refer to this table in regards to the NPM scripts:
|
|
346
|
-
|
|
347
|
-
| Scripts | Actions |
|
|
348
|
-
|-------------|:---------------------------------------------------------------------------------------------------:|
|
|
349
|
-
| dev:nobuild | Runs Vite dev server without running `build:wasm` |
|
|
350
|
-
| dev | Runs Vite dev server and builds a new WASM files through `build:wasm`. |
|
|
351
|
-
| build | Builds the WASM and JS through `build:wasm` and `build:js` and outputs files to `dist` folder. |
|
|
352
|
-
| build:js | Builds the ESM bundles and CJS modules for the Javascript library. |
|
|
353
|
-
| build:wasm | Builds the WASM files through `wasm-pack` and outputs files to a `pkg` directory. |
|
|
354
|
-
| test | Runs tests through Vitest. |
|
|
355
|
-
| type:check | Runs `tsc` to check types in the `src` directory. |
|
|
356
|
-
| gen:data | Generates JSON files for compatibility data and usage data and outputs them to the `gen` directory. |
|
|
357
|
-
|
|
358
|
-
---
|
|
359
|
-
|
|
360
|
-
## Credits
|
|
361
|
-
|
|
362
|
-
This project wouldn't be possible without amazing projects providing the data necessary to perform these compatibility checks.
|
|
363
|
-
|
|
364
|
-
The [browser-compat-data](https://github.com/mdn/browser-compat-data) project by [MDN](https://github.com/mdn) is the single reason why this project was made possible. Make sure to check out their project as it compiles a large majority of modern
|
|
365
|
-
web features across multiple different browser environments.
|
|
366
|
-
|
|
367
|
-
The [caniuse-db](https://github.com/Fyrd/caniuse) package also plays a big role in keeping up-to-date with the global usage data of browsers and their market share.
|
|
368
|
-
|
|
369
|
-
Make sure to check out both of these great projects!
|
|
370
|
-
|
|
371
|
-
---
|
|
372
|
-
|
|
373
|
-
## Package Features Checklist
|
|
374
|
-
|
|
375
|
-
- [x] Cross-browser compatibility based on MDN's browser-compat-data package
|
|
376
|
-
- [x] Configurable cross-browser compatibility DOM inspection
|
|
377
|
-
- [x] Full page cross-browser compatibility scan
|
|
378
|
-
- [x] HTML parsing and compatibility checks via Rust and WASM engine module
|
|
379
|
-
- [x] Interactive panel for viewing results of compatibility checks
|
|
380
|
-
- [x] Hints for improving cross-browser compatibility based on checks
|
|
381
|
-
- [ ] Interactive DOM tree to make inspecting HTML more accurate.
|
|
382
|
-
- [ ] Optional accessibility evaluation and hints based on WCAG guidelines
|
|
383
|
-
- [ ] CSS and Javascript file parsing and cross-browser compatibility checks
|
|
1
|
+
<h1 align="center">Shinkom</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong><em><span style="font-style:italic;">Shinkom</span></em>, the high-speed rail for real-time cross-browser compatibility analysis for websites.<br>
|
|
5
|
+
A JavaScript library powered by a Rust/WASM engine, providing native speed cross-browser compatibility data processing and analysis.<br>
|
|
6
|
+
</strong>
|
|
7
|
+
</p>
|
|
8
|
+
<div align="center">
|
|
9
|
+
<img width="500" height="500" alt="shinkom-logo" src="https://github.com/user-attachments/assets/54e9aa80-3a85-44d5-9d7f-9266303eb156" />
|
|
10
|
+
</div>
|
|
11
|
+
|
|
12
|
+
## Introduction
|
|
13
|
+
|
|
14
|
+
**Shinkom** is a JavaScript library for real-time website cross-browser compatibility analysis.
|
|
15
|
+
|
|
16
|
+
It is *compatible* with many popular libraries and frameworks such as **React, Vue, NextJs, Nuxt** and Vanilla JS.
|
|
17
|
+
It is also accessible in **Node.Js**, [see more on Node.Js usage here](#nodejs).
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Purpose
|
|
22
|
+
|
|
23
|
+
The web has evolved a lot and so have browsers. Among the most popular browsers such as **Chrome, Firefox, Edge, Safari, Opera** and the like,
|
|
24
|
+
there are always new browsers being developed aiming to push the boundaries of what is capable of existing browser technology.
|
|
25
|
+
However, this causes a discrepency in the feature-set between modern browsers since they may use differing technology and architecture
|
|
26
|
+
when developing new browsers.
|
|
27
|
+
Web technology and languages such as **HTML, CSS and JavaScript** are constantly evolving which aids in the problem of features
|
|
28
|
+
either being widely supported or having limited support between browsers.
|
|
29
|
+
|
|
30
|
+
This makes cross-browser compatibility all the more important for a web developer to consider as neglecting this could lead
|
|
31
|
+
to users on other browsers having a poor experience visiting a website due to broken layouts, styling or functionality.
|
|
32
|
+
However, testing for compatibility on different browsers can often become tedious due to the volume of different browsers
|
|
33
|
+
and the many versions of each single one.
|
|
34
|
+
|
|
35
|
+
This is where **Shinkom** connects the rails!
|
|
36
|
+
|
|
37
|
+
The purpose of this library is to provide web developers an intuitive library for analysing the compatibility of a website in real-time during development.
|
|
38
|
+
This project depends heavily on the [@mdn/browser-compat-data](https://github.com/mdn/browser-compat-data/tree/main) project by MDN, which stores a large amount of compatibility data about
|
|
39
|
+
browsers and web features.
|
|
40
|
+
|
|
41
|
+
Most online browser compatibility websites usually require payment for the use of their services and don't often allow for
|
|
42
|
+
finer control of what specifically to test within the website.
|
|
43
|
+
Shinkom aims to provide that fine level of control, to allow web developers to discover the compatibility of their components
|
|
44
|
+
across many browsers during development.
|
|
45
|
+
|
|
46
|
+
This library can also make it easier to identify which specific browsers to test immediately without having to sift through documentation
|
|
47
|
+
to check if a feature works on a particular browser or test the website on every browser to discover potential issues.
|
|
48
|
+
|
|
49
|
+
**Shinkom conducts the analysis of the website content and browser compatibility data and delivers the compatibility result as fast as a bullet train.**
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## IMPORTANT
|
|
54
|
+
|
|
55
|
+
### WebAssembly
|
|
56
|
+
|
|
57
|
+
It is important to mention that this project is made with **WebAssembly** through [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen).
|
|
58
|
+
Therefore, the engine will need to be initialized asynchronously and your server will need to accept the `application/wasm` MIME type.
|
|
59
|
+
It is recommended to read relevant documentation in whichever framework or bundler you are using to apply the correct configuration to accept
|
|
60
|
+
WASM files on your server or visit the [examples](/examples) directory, if your framework or bundler of choice is listed there for a working example.
|
|
61
|
+
|
|
62
|
+
### Server-side Rendering Applications
|
|
63
|
+
|
|
64
|
+
The core engine of Shinkom can be run in Node.js environments, but this is not true for the UI components and the Shinkom entry-point as they are browser-only.
|
|
65
|
+
If using a framework that uses SSR, make sure to initialize the library in hooks that perform side-effects (i.e. `useEffect` or `onMounted`) to prevent
|
|
66
|
+
`window is undefined` errors during SSR pre-rendering.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Getting Started
|
|
71
|
+
|
|
72
|
+
Shinkom can be installed from npm via the `shinkom` package
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npm install -D shinkom
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Once installed, you can then import the Shinkom package in JavaScript.
|
|
79
|
+
Shinkom can be used in frontend frameworks, bundlers and vanilla JS.
|
|
80
|
+
|
|
81
|
+
### Vanilla JS
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
import { Shinkom } from 'shinkom'
|
|
85
|
+
|
|
86
|
+
const shinkom = new Shinkom()
|
|
87
|
+
|
|
88
|
+
shinkom.init()
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### React
|
|
92
|
+
|
|
93
|
+
```javascript
|
|
94
|
+
import React, { useEffect } from 'react'
|
|
95
|
+
import { Shinkom } from 'shinkom'
|
|
96
|
+
|
|
97
|
+
export default function App() {
|
|
98
|
+
useEffect(() => {
|
|
99
|
+
const shinkom = new Shinkom()
|
|
100
|
+
|
|
101
|
+
shinkom.init()
|
|
102
|
+
|
|
103
|
+
return () => shinkom.destroy()
|
|
104
|
+
}, [])
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Vue
|
|
109
|
+
|
|
110
|
+
```javascript
|
|
111
|
+
<script setup lang="ts">
|
|
112
|
+
import { onMounted, onUnmounted } from 'vue'
|
|
113
|
+
import { Shinkom } from 'shinkom'
|
|
114
|
+
import wasm from 'shinkom/wasm?url'
|
|
115
|
+
|
|
116
|
+
const shinkom = new Shinkom({
|
|
117
|
+
engine: {
|
|
118
|
+
wasmURL: wasm
|
|
119
|
+
}
|
|
120
|
+
})
|
|
121
|
+
|
|
122
|
+
onMounted(() => {
|
|
123
|
+
shinkom.init()
|
|
124
|
+
})
|
|
125
|
+
|
|
126
|
+
onUnmounted(() => {
|
|
127
|
+
shinkom.destroy()
|
|
128
|
+
})
|
|
129
|
+
</script>
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
You can also use Shinkom through the `require` statement in commonJS.
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
const Shinkom = require('shinkom').Shinkom
|
|
136
|
+
|
|
137
|
+
const shinkom = new Shinkom()
|
|
138
|
+
|
|
139
|
+
shinkom.init()
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
If there are other frameworks or bundlers not listed here as being supported that you would like to use Shinkom with,
|
|
143
|
+
then consider contributing by creating a **pull request** on the **dev** branch to support it and make sure to **create an example for others!**
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Usage
|
|
148
|
+
|
|
149
|
+
### Basic
|
|
150
|
+
|
|
151
|
+
The simplest and **recommended** way to utilize Shinkom is through the main entry-point.
|
|
152
|
+
|
|
153
|
+
```javascript
|
|
154
|
+
import { Shinkom } from 'shinkom'
|
|
155
|
+
|
|
156
|
+
const shinkom = new Shinkom()
|
|
157
|
+
|
|
158
|
+
shinkom.init()
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
This enables the use of the **interactive UI and Rust/WASM engine** in order to inspect elements on a page.
|
|
162
|
+
|
|
163
|
+
### Modular
|
|
164
|
+
|
|
165
|
+
Shinkom was made to be **modular**, meaning you can also choose to use individual modules that you would
|
|
166
|
+
like to make use of for finer control.
|
|
167
|
+
|
|
168
|
+
```javascript
|
|
169
|
+
import { ShinkomBus, ShinkomState, SKEngine, CompatInspector, CompatUI } from 'shinkom'
|
|
170
|
+
|
|
171
|
+
const bus = new ShinkomBus()
|
|
172
|
+
const state = new ShinkomState()
|
|
173
|
+
const engine = new SKEngine(bus)
|
|
174
|
+
const inspector = new CompatInspector(bus, state)
|
|
175
|
+
const ui = new CompatUI(bus, state, [inspector])
|
|
176
|
+
|
|
177
|
+
ui.init()
|
|
178
|
+
engine.initEngine()
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Engine
|
|
182
|
+
|
|
183
|
+
The **Rust/WASM engine** can be used separately from the UI components in cases where you may want to automate
|
|
184
|
+
compatibility inspection without manually having to interact with a page.
|
|
185
|
+
|
|
186
|
+
```javascript
|
|
187
|
+
import { SKEngine } from 'shinkom/engine'
|
|
188
|
+
|
|
189
|
+
const engine = new SKEngine()
|
|
190
|
+
|
|
191
|
+
const run = async () => {
|
|
192
|
+
await engine.initEngine()
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
await run()
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
If needed, you can also **preload** the WASM file for **lazy initialization** of the engine,
|
|
199
|
+
this can be particularly useful when using the engine in **SSR applications** to eliminate
|
|
200
|
+
constant cold starts.
|
|
201
|
+
|
|
202
|
+
```javascript
|
|
203
|
+
import { SKEngine } from 'shinkom/engine'
|
|
204
|
+
|
|
205
|
+
const engine = new SKEngine()
|
|
206
|
+
|
|
207
|
+
const preLoad = async () => {
|
|
208
|
+
await engine.loadWasm()
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
await preLoad()
|
|
212
|
+
|
|
213
|
+
// other operations //
|
|
214
|
+
|
|
215
|
+
await engine.initEngine()
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Compatibility Checks
|
|
221
|
+
|
|
222
|
+
### Schema
|
|
223
|
+
|
|
224
|
+
In order to discover potential compatibility issues, Shinkom implements a score metric for the result of the compatibility check.
|
|
225
|
+
|
|
226
|
+
The general schema that an average compatibility check will follow goes like this:
|
|
227
|
+
|
|
228
|
+
```javascript
|
|
229
|
+
{
|
|
230
|
+
"lookup_results": [
|
|
231
|
+
// results for each web feature
|
|
232
|
+
{
|
|
233
|
+
"name": "fake-element", // name of the web feature
|
|
234
|
+
"mdn_url": "https://developer.mozilla.org/docs/web/HTML/Reference/Elements/fake-element", // link that leads to MDN documentation of the web feature
|
|
235
|
+
"compat_score": "100.00", // score based on the sum of the browser_score and status_score over the max compat score
|
|
236
|
+
"browser_score": "100.00", // score based on the sum of weighted scores in each browser
|
|
237
|
+
"status_score": "100.00", // score based on the status object in compatibility data
|
|
238
|
+
"browsers": [
|
|
239
|
+
// results for each checked browser
|
|
240
|
+
{
|
|
241
|
+
"browser_name": "edge", // name of the browser
|
|
242
|
+
"score": {
|
|
243
|
+
"raw_score": "100.00", // score based on the safety of feature in browser
|
|
244
|
+
"weighted_score": "5.74", // score based on the usage of edge over the total market share between checked browsers
|
|
245
|
+
},
|
|
246
|
+
"versions": {
|
|
247
|
+
"version_added": "34" // feature added in edge engine version 34
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
]
|
|
251
|
+
}
|
|
252
|
+
],
|
|
253
|
+
// the overall score of the compatibility check
|
|
254
|
+
"overall_score": 100
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
This object consists of the following:
|
|
259
|
+
|
|
260
|
+
- The `overall_score` property is a number that represents the final score of the compatibility check. It is a sum of each `compat_score` a
|
|
261
|
+
web feature has been given.
|
|
262
|
+
- The `lookup_results` property is an array of objects that contains each web feature's individual compatibility results.
|
|
263
|
+
- The `name` property is a string representing the name of the web feature.
|
|
264
|
+
- The `mdn_url` property is a string containing a link to the MDN Web Docs documentation for the web feature.
|
|
265
|
+
- The `compat_score` property is a string representing the calculated score for the web feature. It is calculated by summing the `browser_score` and `status_score`
|
|
266
|
+
and then dividing that sum by the total compatibility score a feature can get (currently 200).
|
|
267
|
+
- The `browser_score` property is a string representing the sum of the `weighted_score`'s between each browser for the web feature.
|
|
268
|
+
- The `status_score` property is a string representing the calculated score based on the current status of this web feature (standard_track, experimental, or deprecated).
|
|
269
|
+
- The `browsers` property is an array of objects that contains each browsers individual compatibility results.
|
|
270
|
+
- The `browser_name` property is a string representing the name of the checked browser.
|
|
271
|
+
- The `score` property is an object containing the `raw_score` and `weighted_score` for the web feature in a particular browser.
|
|
272
|
+
- `raw_score` is the calculated score before weighting is applied, which can be interpreted as the *safety* of a web feature.
|
|
273
|
+
- `weighted_score` is the raw score but with a weighting multiplier calculated as such: **total_browser_usage / market_share**.
|
|
274
|
+
- The `versions` property can be either an object or an array of objects depending on whether the web feature has been added, removed or partially implemented
|
|
275
|
+
in many different versions or just one version.
|
|
276
|
+
|
|
277
|
+
### Scoring
|
|
278
|
+
|
|
279
|
+
The scoring for the compatibility check is an important feature to make sure that it gives fair and understandable results that won't leave you
|
|
280
|
+
guessing why a check resulted in a particular score.
|
|
281
|
+
|
|
282
|
+
The table below lists the score types and their respective formulas:
|
|
283
|
+
|
|
284
|
+
| Score Type | Formula |
|
|
285
|
+
|----------------|:-------------------------------------------------------------------------------------------:|
|
|
286
|
+
| overall_score | (compat_score~1~ + compat_score~2~ + ... compat_score~n~) / N |
|
|
287
|
+
| compat_score | ((browser_score + status_score) / MAX_COMPAT_SCORE) * 100 |
|
|
288
|
+
| browser_score | ((weighted_score~1~ + weighted_score~2~ + ... weighted_score~n~) / MAX_BROWSER_SCORE) * 100 |
|
|
289
|
+
| status_score | (status_score / MAX_STATUS_SCORE) * 100 |
|
|
290
|
+
| raw_score | Raw score calculation explained below |
|
|
291
|
+
| weighted_score | raw_score * (total_usage / market_share) |
|
|
292
|
+
|
|
293
|
+
Here are a few things to clarify about these formulas:
|
|
294
|
+
|
|
295
|
+
- In `overall_score`, *N* represents the number of lookup results returned.
|
|
296
|
+
- `MAX_COMPAT_SCORE` has a value of 200, whereas `MAX_BROWSER_SCORE` and `MAX_STATUS_SCORE` have a value of 100.
|
|
297
|
+
- The `raw_score` is calculated based on many different factors.
|
|
298
|
+
- If the current version of the browser is greater than the `version_added` value, the score is 100. This is
|
|
299
|
+
also the case if `version_added` is set to `true`.
|
|
300
|
+
- If the `version_removed` value is greater than the `version_added` value, the score is 0 since it is a removed feature.
|
|
301
|
+
- If the `partial_implementation` value is set to true, the score is 80.
|
|
302
|
+
- `total_usage` is the usage of a browser across all of its versions, and the `market_share` is the sum of `total_usage`
|
|
303
|
+
between every browser.
|
|
304
|
+
- The `browser_score` is the sum of the weighted scores from each browser divided by the `MAX_BROWSER_SCORE`.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## Node.js
|
|
309
|
+
|
|
310
|
+
Shinkom can be utilised in Node environments through its Engine module.
|
|
311
|
+
The UI components are strictly for browser environments, however the engine itself can be used independently in both environments.
|
|
312
|
+
|
|
313
|
+
### ESM Bundles
|
|
314
|
+
|
|
315
|
+
```javascript
|
|
316
|
+
import { SKEngine } from 'shinkom/engine'
|
|
317
|
+
|
|
318
|
+
const skEngine = new SKEngine()
|
|
319
|
+
|
|
320
|
+
await skEngine.initEngine()
|
|
321
|
+
|
|
322
|
+
skEngine.checkElement(`<div id="test-div" class="test-classes">Test Div</div>`)
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### CommonJS Modules
|
|
326
|
+
|
|
327
|
+
```javascript
|
|
328
|
+
const SKEngine = require('shinkom/engine').SKEngine
|
|
329
|
+
|
|
330
|
+
const skEngine = new SKEngine()
|
|
331
|
+
|
|
332
|
+
const run = async () => {
|
|
333
|
+
await skEngine.initEngine()
|
|
334
|
+
|
|
335
|
+
skEngine.checkElement(`<div id="test-div" class="test-classes">Test Div</div>`)
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
run()
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Development Scripts
|
|
344
|
+
|
|
345
|
+
When cloning or forking this library, refer to this table in regards to the NPM scripts:
|
|
346
|
+
|
|
347
|
+
| Scripts | Actions |
|
|
348
|
+
|-------------|:---------------------------------------------------------------------------------------------------:|
|
|
349
|
+
| dev:nobuild | Runs Vite dev server without running `build:wasm` |
|
|
350
|
+
| dev | Runs Vite dev server and builds a new WASM files through `build:wasm`. |
|
|
351
|
+
| build | Builds the WASM and JS through `build:wasm` and `build:js` and outputs files to `dist` folder. |
|
|
352
|
+
| build:js | Builds the ESM bundles and CJS modules for the Javascript library. |
|
|
353
|
+
| build:wasm | Builds the WASM files through `wasm-pack` and outputs files to a `pkg` directory. |
|
|
354
|
+
| test | Runs tests through Vitest. |
|
|
355
|
+
| type:check | Runs `tsc` to check types in the `src` directory. |
|
|
356
|
+
| gen:data | Generates JSON files for compatibility data and usage data and outputs them to the `gen` directory. |
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## Credits
|
|
361
|
+
|
|
362
|
+
This project wouldn't be possible without amazing projects providing the data necessary to perform these compatibility checks.
|
|
363
|
+
|
|
364
|
+
The [browser-compat-data](https://github.com/mdn/browser-compat-data) project by [MDN](https://github.com/mdn) is the single reason why this project was made possible. Make sure to check out their project as it compiles a large majority of modern
|
|
365
|
+
web features across multiple different browser environments.
|
|
366
|
+
|
|
367
|
+
The [caniuse-db](https://github.com/Fyrd/caniuse) package also plays a big role in keeping up-to-date with the global usage data of browsers and their market share.
|
|
368
|
+
|
|
369
|
+
Make sure to check out both of these great projects!
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## Package Features Checklist
|
|
374
|
+
|
|
375
|
+
- [x] Cross-browser compatibility based on MDN's browser-compat-data package
|
|
376
|
+
- [x] Configurable cross-browser compatibility DOM inspection
|
|
377
|
+
- [x] Full page cross-browser compatibility scan
|
|
378
|
+
- [x] HTML parsing and compatibility checks via Rust and WASM engine module
|
|
379
|
+
- [x] Interactive panel for viewing results of compatibility checks
|
|
380
|
+
- [x] Hints for improving cross-browser compatibility based on checks
|
|
381
|
+
- [ ] Interactive DOM tree to make inspecting HTML more accurate.
|
|
382
|
+
- [ ] Optional accessibility evaluation and hints based on WCAG guidelines
|
|
383
|
+
- [ ] CSS and Javascript file parsing and cross-browser compatibility checks
|