Skip to content

Commit 798d6f3

Browse files
Copilothotlong
andcommitted
feat(sdk): Add comprehensive browser compatibility support and documentation
- Add detailed README.md with browser usage examples - Add package.json browser field and enhanced metadata - Add browser example with interactive HTML demo - Add polyfill guidance for AbortSignal.timeout - Add React/Vue.js hook examples - Improve package discoverability with expanded keywords Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent cf5875d commit 798d6f3

6 files changed

Lines changed: 1234 additions & 3 deletions

File tree

examples/browser/README.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Browser Example for @objectql/sdk
2+
3+
This example demonstrates how to use `@objectql/sdk` directly in a browser environment without any build tools.
4+
5+
## 🚀 Quick Start
6+
7+
### Prerequisites
8+
9+
You need a running ObjectQL server. You can start one using:
10+
11+
```bash
12+
# From the repository root
13+
cd examples/starters/hello-world
14+
npm install
15+
npm start
16+
```
17+
18+
The server will be available at `http://localhost:3000`.
19+
20+
### Running the Browser Example
21+
22+
1. **Open the HTML file directly in a browser:**
23+
24+
```bash
25+
# Open in your default browser
26+
open index.html # macOS
27+
xdg-open index.html # Linux
28+
start index.html # Windows
29+
```
30+
31+
2. **Or serve it with a simple HTTP server:**
32+
33+
```bash
34+
# Using Python
35+
python3 -m http.server 8080
36+
37+
# Using Node.js http-server
38+
npx http-server -p 8080
39+
40+
# Using PHP
41+
php -S localhost:8080
42+
```
43+
44+
Then navigate to `http://localhost:8080` in your browser.
45+
46+
## 📋 Features Demonstrated
47+
48+
The example shows how to:
49+
50+
- ✅ Initialize `DataApiClient` and `MetadataApiClient` in the browser
51+
- ✅ List records with filtering and pagination
52+
- ✅ Get object metadata and schema
53+
- ✅ Create new records
54+
- ✅ Count records with filters
55+
- ✅ Handle errors and loading states
56+
- ✅ Use polyfill for `AbortSignal.timeout` for older browsers
57+
58+
## 🌐 Browser Compatibility
59+
60+
This example works in all modern browsers:
61+
62+
- Chrome 103+
63+
- Firefox 100+
64+
- Safari 16.4+
65+
- Edge 103+
66+
67+
For older browsers, the example includes a polyfill for `AbortSignal.timeout`.
68+
69+
## 🔧 Using in Production
70+
71+
For production applications, we recommend:
72+
73+
### Option 1: Using a Module Bundler (Recommended)
74+
75+
```bash
76+
npm install @objectql/sdk @objectql/types
77+
```
78+
79+
```javascript
80+
import { DataApiClient, MetadataApiClient } from '@objectql/sdk';
81+
82+
const client = new DataApiClient({
83+
baseUrl: process.env.API_URL
84+
});
85+
```
86+
87+
### Option 2: Using ES Modules via CDN
88+
89+
```html
90+
<script type="module">
91+
import { DataApiClient } from 'https://cdn.skypack.dev/@objectql/sdk';
92+
93+
const client = new DataApiClient({
94+
baseUrl: 'https://api.example.com'
95+
});
96+
</script>
97+
```
98+
99+
### Option 3: Self-hosted ES Modules
100+
101+
After building the package, you can serve the dist files:
102+
103+
```html
104+
<script type="module">
105+
import { DataApiClient } from '/node_modules/@objectql/sdk/dist/index.js';
106+
107+
const client = new DataApiClient({
108+
baseUrl: 'http://localhost:3000'
109+
});
110+
</script>
111+
```
112+
113+
## 🔒 Security Considerations
114+
115+
When using the SDK in the browser:
116+
117+
1. **Never hardcode sensitive tokens** - Store them in environment variables or secure storage
118+
2. **Use HTTPS** in production
119+
3. **Implement CORS** properly on your ObjectQL server
120+
4. **Validate all user input** before sending to the API
121+
5. **Use Content Security Policy (CSP)** headers
122+
123+
## 📚 Additional Resources
124+
125+
- [ObjectQL SDK Documentation](../../packages/drivers/sdk/README.md)
126+
- [Client SDK API Guide](../../docs/api/client-sdk.md)
127+
- [REST API Reference](../../docs/api/rest.md)
128+
- [ObjectQL Website](https://objectql.org)
129+
130+
## 🤝 Contributing
131+
132+
Found an issue or want to improve this example? Please open an issue or submit a PR!

0 commit comments

Comments
 (0)