jmri-client 3.2.0 → 3.2.1

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.
Files changed (3) hide show
  1. package/README.md +2 -0
  2. package/docs/BROWSER.md +52 -4
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -13,6 +13,7 @@ WebSocket client for [JMRI](http://jmri.sourceforge.net/) with real-time updates
13
13
  - ✅ **WebSocket-based** - Real-time bidirectional communication
14
14
  - ✅ **Event-driven** - Subscribe to power changes, throttle updates, and more
15
15
  - ✅ **Full Throttle Control** - Speed (0.0-1.0), direction, and functions (F0-F28)
16
+ - ✅ **Browser & Node.js** - Works in browsers and Node.js with auto-detection
16
17
  - ✅ **Mock Mode** - Test and demo without JMRI hardware
17
18
  - ✅ **Auto-reconnection** - Exponential backoff with jitter
18
19
  - ✅ **Heartbeat monitoring** - Automatic ping/pong keepalive
@@ -61,6 +62,7 @@ await client.disconnect();
61
62
  ## Documentation
62
63
 
63
64
  - **[API Reference](docs/API.md)** - Complete API documentation
65
+ - **[Browser Usage](docs/BROWSER.md)** - Using jmri-client in web browsers
64
66
  - **[Examples](docs/EXAMPLES.md)** - Common usage patterns
65
67
  - **[Mock Mode](docs/MOCK_MODE.md)** - Testing without hardware
66
68
  - **[Migration Guide](docs/MIGRATION.md)** - Upgrading from v2.x
package/docs/BROWSER.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Browser Usage Guide
2
2
 
3
- jmri-client v3.1.0+ supports both Node.js and browser environments. This guide shows how to use jmri-client in web applications.
3
+ jmri-client v3.2.0+ supports both Node.js and browser environments. This guide shows how to use jmri-client in web applications.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,6 +8,21 @@ jmri-client v3.1.0+ supports both Node.js and browser environments. This guide s
8
8
  npm install jmri-client
9
9
  ```
10
10
 
11
+ ## Browser Bundle vs ESM Build
12
+
13
+ jmri-client provides two builds for different use cases:
14
+
15
+ - **Browser Bundle** (`dist/browser/jmri-client.js`) - ✅ **Recommended for browsers**
16
+ - All dependencies bundled (including eventemitter3)
17
+ - Ready to use in browsers without additional configuration
18
+ - Works with direct imports, CDN usage, and module bundlers
19
+
20
+ - **ESM Build** (`dist/esm/index.js`) - For Node.js with ESM
21
+ - Requires module resolution for dependencies
22
+ - Used automatically in Node.js environments
23
+
24
+ **Important:** When using jmri-client in browsers, always use the **browser bundle** to ensure proper functionality, especially for reconnection features.
25
+
11
26
  ## Browser Compatibility
12
27
 
13
28
  jmri-client automatically detects the environment and uses:
@@ -20,7 +35,7 @@ No configuration or polyfills required!
20
35
 
21
36
  ### Using a Module Bundler (Recommended)
22
37
 
23
- With Webpack, Vite, Rollup, or similar bundlers:
38
+ With Webpack, Vite, Rollup, or similar bundlers, the browser bundle is automatically used via the `browser` field in package.json:
24
39
 
25
40
  ```javascript
26
41
  import { JmriClient } from 'jmri-client';
@@ -51,9 +66,37 @@ await client.setThrottleSpeed(throttleId, 0.5); // Half speed
51
66
  await client.setThrottleFunction(throttleId, 'F0', true); // Headlight on
52
67
  ```
53
68
 
69
+ **Note:** Most modern bundlers (Vite, Webpack 5+, etc.) automatically use the browser bundle via the `browser` field in package.json. If your bundler doesn't support this, you may need to add an alias:
70
+
71
+ **Vite:**
72
+ ```typescript
73
+ // vite.config.ts
74
+ import { fileURLToPath, URL } from 'node:url'
75
+
76
+ export default defineConfig({
77
+ resolve: {
78
+ alias: {
79
+ 'jmri-client': fileURLToPath(new URL('./node_modules/jmri-client/dist/browser/jmri-client.js', import.meta.url))
80
+ }
81
+ }
82
+ })
83
+ ```
84
+
85
+ **Webpack:**
86
+ ```javascript
87
+ // webpack.config.js
88
+ module.exports = {
89
+ resolve: {
90
+ alias: {
91
+ 'jmri-client': path.resolve(__dirname, 'node_modules/jmri-client/dist/browser/jmri-client.js')
92
+ }
93
+ }
94
+ }
95
+ ```
96
+
54
97
  ### Using a CDN (ES Modules)
55
98
 
56
- For quick prototypes without a build step:
99
+ For quick prototypes without a build step, use the browser bundle:
57
100
 
58
101
  ```html
59
102
  <!DOCTYPE html>
@@ -68,7 +111,8 @@ For quick prototypes without a build step:
68
111
  <button id="speed">Set Speed 50%</button>
69
112
 
70
113
  <script type="module">
71
- import { JmriClient } from 'https://cdn.jsdelivr.net/npm/jmri-client@3.1.0/dist/esm/index.js';
114
+ // Use the browser bundle from CDN
115
+ import { JmriClient } from 'https://unpkg.com/jmri-client@3.2.1/dist/browser/jmri-client.js';
72
116
 
73
117
  const client = new JmriClient({
74
118
  host: 'localhost',
@@ -99,6 +143,10 @@ For quick prototypes without a build step:
99
143
  </html>
100
144
  ```
101
145
 
146
+ Alternative CDNs:
147
+ - **unpkg**: `https://unpkg.com/jmri-client@3.2.1/dist/browser/jmri-client.js`
148
+ - **jsDelivr**: `https://cdn.jsdelivr.net/npm/jmri-client@3.2.1/dist/browser/jmri-client.js`
149
+
102
150
  ## React Example
103
151
 
104
152
  ```jsx
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "jmri-client",
3
- "version": "3.2.0",
3
+ "version": "3.2.1",
4
4
  "description": "WebSocket client for JMRI with real-time updates and throttle control - works in both Node.js and browsers",
5
5
  "main": "./dist/cjs/index.js",
6
6
  "module": "./dist/esm/index.js",
7
- "browser": "./dist/esm/index.js",
7
+ "browser": "./dist/browser/jmri-client.js",
8
8
  "types": "./dist/types/index.d.ts",
9
9
  "exports": {
10
10
  ".": {
11
- "browser": "./dist/esm/index.js",
11
+ "browser": "./dist/browser/jmri-client.js",
12
12
  "import": "./dist/esm/index.js",
13
13
  "require": "./dist/cjs/index.js",
14
14
  "types": "./dist/types/index.d.ts"