Skip to content

Commit d595752

Browse files
melvincarvalhomelvincarvalho
committed
v0.1.2 - Optimized npm package (585KB tarball) + auto-render
1 parent 9c2aad9 commit d595752

File tree

9 files changed

+1806
-20
lines changed

9 files changed

+1806
-20
lines changed

‎CHANGES-FROM-UPSTREAM.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# JSS Stack - Changes from Upstream SolidOS
2+
3+
This document tracks all modifications made to create the JavaScriptSolidServer (JSS) authentication and UI stack, replacing @inrupt/solid-client-authn-browser with a minimal solid-oidc implementation.
4+
5+
## Overview
6+
7+
The JSS stack replaces the standard SolidOS/mashlib authentication with a lightweight solid-oidc implementation. This reduces bundle size and removes the dependency on @inrupt packages.
8+
9+
```
10+
┌─────────────────────────────────────────────────────────────┐
11+
│ solid-shim │
12+
│ (mashlib replacement - 1.89MB) │
13+
├─────────────────────────────────────────────────────────────┤
14+
│ solid-panes-jss │ solid-ui-jss │ solid-logic-jss │
15+
├───────────────────┴────────────────┴────────────────────────┤
16+
│ solid-oidc │
17+
│ (minimal OIDC + DPoP tokens) │
18+
└─────────────────────────────────────────────────────────────┘
19+
```
20+
21+
---
22+
23+
## Package Changes
24+
25+
### 1. solid-oidc
26+
27+
**Repository:** `github:JavaScriptSolidServer/solid-oidc`
28+
**Upstream:** New package (no upstream)
29+
30+
Minimal Solid-OIDC implementation providing:
31+
- Authorization Code Grant with PKCE
32+
- Dynamic Client Registration
33+
- DPoP token binding
34+
- Session management with IndexedDB storage
35+
- Refresh token support
36+
37+
**Key files:**
38+
- `solid-oidc.js` - Main implementation
39+
- `src/Session.js` - Session management
40+
- `src/SessionDatabase.js` - IndexedDB storage
41+
42+
**Notable implementation details:**
43+
- Uses `jose` npm package (not CDN) for JWT handling
44+
- Implements manual token exchange for servers without proper redirect support
45+
- ~500 lines vs ~50,000+ in @inrupt/solid-client-authn-browser
46+
47+
---
48+
49+
### 2. solid-logic-jss
50+
51+
**Repository:** `JavaScriptSolidServer/solid-logic-jss`
52+
**Upstream:** `SolidOS/solid-logic`
53+
**Version:** 4.1.0
54+
55+
**Changes from upstream:**
56+
57+
1. **Authentication provider swap:**
58+
```diff
59+
- import { Session } from '@inrupt/solid-client-authn-browser'
60+
+ import { Session } from 'solid-oidc'
61+
```
62+
63+
2. **Package.json dependencies:**
64+
```diff
65+
- "@inrupt/solid-client-authn-browser": "^2.0.0"
66+
+ "solid-oidc": "github:JavaScriptSolidServer/solid-oidc"
67+
```
68+
69+
3. **TypeScript config:**
70+
- Added `skipLibCheck: true` to handle rdflib type issues
71+
72+
4. **Build outputs:**
73+
- `dist/solid-logic.esm.js` - ESM bundle for webpack
74+
- `dist/solid-logic.umd.js` - UMD bundle
75+
76+
---
77+
78+
### 3. solid-ui-jss
79+
80+
**Repository:** `JavaScriptSolidServer/solid-ui-jss`
81+
**Upstream:** `SolidOS/solid-ui`
82+
**Version:** 3.x
83+
84+
**Changes from upstream:**
85+
86+
1. **Dependency swap:**
87+
```diff
88+
- "solid-logic": "^4.0.0"
89+
+ "solid-logic-jss": "^4.1.0"
90+
```
91+
92+
2. **Import updates:**
93+
All imports of `solid-logic` changed to `solid-logic-jss`
94+
95+
3. **Build outputs:**
96+
- `dist/solid-ui.esm.js` - ESM bundle (used by solid-shim)
97+
- `dist/solid-ui.umd.js` - UMD bundle
98+
99+
---
100+
101+
### 4. solid-panes-jss
102+
103+
**Repository:** `JavaScriptSolidServer/solid-panes-jss`
104+
**Upstream:** `SolidOS/solid-panes`
105+
**Version:** 4.0.1
106+
107+
**Changes from upstream:**
108+
109+
1. **Dependency swaps:**
110+
```diff
111+
- "solid-logic": "^4.0.0"
112+
- "solid-ui": "^3.0.0"
113+
- "profile-pane": "^2.0.0"
114+
+ "solid-logic-jss": "^4.1.0"
115+
+ "solid-ui-jss": "^3.0.0"
116+
+ "profile-pane-jss": "^2.1.0"
117+
```
118+
119+
2. **Import updates in `src/registerPanes.js`:**
120+
```diff
121+
- import profilePane from 'profile-pane'
122+
+ import profilePane from 'profile-pane-jss'
123+
```
124+
125+
3. **Dev files updated:**
126+
- `dev/pane/index.ts`
127+
- `dev/loader.ts`
128+
129+
---
130+
131+
### 5. profile-pane-jss
132+
133+
**Repository:** `JavaScriptSolidServer/profile-pane-jss`
134+
**Upstream:** `SolidOS/profile-pane`
135+
**Version:** 2.1.0
136+
137+
**Changes from upstream:**
138+
139+
1. **Package renamed:**
140+
```diff
141+
- "name": "profile-pane"
142+
+ "name": "profile-pane-jss"
143+
```
144+
145+
2. **New JSS brand colors in `src/baseStyles.ts`:**
146+
```typescript
147+
export const jssColors = {
148+
primary: '#7C3AED', // Purple
149+
primaryDark: '#6D28D9',
150+
secondary: '#2563EB', // Blue
151+
gradient: 'linear-gradient(135deg, #7C3AED, #2563EB)',
152+
// ... more colors
153+
}
154+
```
155+
156+
3. **Updated card styles:**
157+
- 16px border radius (was 4px)
158+
- Purple-tinted shadows
159+
- Better spacing
160+
161+
4. **ProfileCard.ts changes:**
162+
- Purple name heading with accent underline
163+
- Uses `jssColors.primary` as default highlight
164+
165+
5. **ProfileView.ts changes:**
166+
- Added JSS badge component on QR code card
167+
- Subtle background gradient
168+
169+
---
170+
171+
### 6. solid-shim (NEW)
172+
173+
**Repository:** `JavaScriptSolidServer/solid-shim`
174+
**Upstream:** None (replaces `SolidOS/mashlib`)
175+
**Version:** 0.2.x
176+
177+
**Purpose:** Drop-in replacement for mashlib using JSS packages.
178+
179+
**Key features:**
180+
181+
1. **Same global interface as mashlib:**
182+
```javascript
183+
window.$rdf = rdflib
184+
window.panes = solid-panes-jss
185+
window.UI = solid-ui-jss
186+
window.SolidLogic = { authn, authSession, store }
187+
window.mashlib = { versionInfo }
188+
```
189+
190+
2. **Webpack configuration (`webpack.config.mjs`):**
191+
- Resolves symlinked packages correctly
192+
- Maps globals ($rdf, UI, SolidLogic) to ESM modules
193+
- Redirects `solid-logic` → `solid-logic-jss`
194+
- Redirects `solid-ui` → `solid-ui-jss`
195+
- Replaces jose CDN URL with npm package
196+
197+
3. **JSS Theme (`src/styles.ts`):**
198+
- Purple/blue gradient header
199+
- Minimal CSS overrides (soft approach)
200+
- Custom scrollbars
201+
- Focus state improvements
202+
203+
4. **Output:**
204+
- `dist/mashlib.min.js` - Main bundle (~1.89MB vs ~4.6MB original)
205+
- `dist/841.mashlib.min.js` - Code-split chunk
206+
207+
---
208+
209+
## Bundle Size Comparison
210+
211+
| Package | Original | JSS Version |
212+
|---------|----------|-------------|
213+
| mashlib | ~4.6 MB | - |
214+
| solid-shim | - | ~1.89 MB |
215+
| **Reduction** | | **~59%** |
216+
217+
---
218+
219+
## How to Use
220+
221+
### For JSS Server
222+
223+
Copy solid-shim dist files to JSS's mashlib-local:
224+
225+
```bash
226+
cp solid-shim/dist/mashlib.min.js \
227+
JavaScriptSolidServer/src/mashlib-local/dist/
228+
229+
cp solid-shim/dist/841.mashlib.min.js \
230+
JavaScriptSolidServer/src/mashlib-local/dist/
231+
```
232+
233+
### For Development
234+
235+
Link all packages locally:
236+
237+
```bash
238+
# In each package directory:
239+
cd solid-oidc && npm link
240+
cd solid-logic-jss && npm link && npm link solid-oidc
241+
cd solid-ui-jss && npm link && npm link solid-logic-jss
242+
cd solid-panes-jss && npm link && npm link solid-logic-jss solid-ui-jss
243+
cd profile-pane-jss && npm link
244+
cd solid-panes-jss && npm link profile-pane-jss
245+
cd solid-shim && npm link solid-logic-jss solid-ui-jss solid-panes-jss
246+
```
247+
248+
---
249+
250+
## Visual Changes
251+
252+
### Header
253+
- Purple/blue gradient: `linear-gradient(135deg, #7C3AED, #2563EB)`
254+
255+
### Profile Pane
256+
- Purple name headings
257+
- JSS badge on QR code card
258+
- Softer card shadows
259+
260+
### Overall
261+
- Minimal CSS intervention
262+
- Original SolidOS styling preserved
263+
- Header gradient is main branding element
264+
265+
---
266+
267+
## Authentication Flow
268+
269+
1. User clicks "Log in"
270+
2. solid-oidc performs Dynamic Client Registration with IdP
271+
3. Redirects to IdP authorization endpoint (Authorization Code + PKCE)
272+
4. IdP redirects back with code
273+
5. solid-oidc exchanges code for tokens
274+
6. DPoP-bound access token used for authenticated requests
275+
7. Session stored in IndexedDB for persistence
276+
277+
---
278+
279+
## Known Differences from @inrupt
280+
281+
1. **No silent authentication** - Requires explicit login
282+
2. **No iframe refresh** - Uses refresh tokens instead
283+
3. **Simpler error handling** - Less defensive
284+
4. **No Node.js support** - Browser-only
285+
286+
---
287+
288+
## Future Work
289+
290+
- [ ] Publish packages to npm under @jss scope
291+
- [ ] Add more pane customizations
292+
- [ ] Improve error messages
293+
- [ ] Add session timeout handling
294+
- [ ] Test with more IdP providers
295+
296+
---
297+
298+
*Last updated: December 2024*

‎index.html‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<head>
55
<meta charset="UTF-8">
66
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7-
<title>SolidOS Browser</title>
7+
<title>jsonos Browser</title>
88
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mashlib/dist/mash.css" />
99
<!-- Using solid-shim instead of mashlib -->
1010
<script src="dist/solid-shim.min.js"></script>
@@ -342,8 +342,8 @@
342342

343343
<header class="header">
344344
<div class="header-content">
345-
<h1>SolidOS Browser</h1>
346-
<p class="header-subtitle">Explore and manage your decentralized data</p>
345+
<h1>jsonos Browser</h1>
346+
<p class="header-subtitle">The JSON Operating System for the Web</p>
347347

348348
<div class="search-container">
349349
<input
@@ -379,7 +379,7 @@ <h1>SolidOS Browser</h1>
379379
<main class="browser-container">
380380
<div class="card">
381381
<div id="welcome" class="welcome-message">
382-
<h2>Welcome to SolidOS Browser</h2>
382+
<h2>Welcome to jsonos</h2>
383383
<p>Enter a URL above or click one of the quick links to get started.</p>
384384
<p>Log in with your WebID to access private data and edit resources.</p>
385385
</div>
@@ -398,8 +398,8 @@ <h2>Welcome to SolidOS Browser</h2>
398398

399399
<footer class="footer">
400400
<p>
401-
Powered by <a href="https://github.com/JavaScriptSolidServer/solid-shim" target="_blank">solid-shim</a> |
402-
<a href="https://solid-docs.github.io/docs/" target="_blank">Developer Docs</a> |
401+
Powered by <a href="https://jsonos.com" target="_blank">jsonos</a> |
402+
<a href="https://github.com/json-os" target="_blank">GitHub</a> |
403403
<a href="https://solidproject.org/" target="_blank">Solid Project</a>
404404
</p>
405405
</footer>
@@ -438,7 +438,7 @@ <h2>Welcome to SolidOS Browser</h2>
438438
const params = new URLSearchParams(location.search)
439439
params.set('uri', uri)
440440
window.history.replaceState({}, '', `${location.origin}${location.pathname}?${params}`)
441-
document.title = `SolidOS Browser - ${uri}`
441+
document.title = `jsonos - ${uri}`
442442

443443
// Load the resource
444444
const subject = $rdf.sym(uri)

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "solid-shim",
3-
"version": "0.1.0",
3+
"version": "0.1.2",
44
"description": "Minimal Solid data browser using solid-panes-jss with solid-oidc authentication",
55
"type": "module",
66
"main": "dist/solid-shim.js",
@@ -13,16 +13,19 @@
1313
}
1414
},
1515
"files": [
16-
"dist/",
16+
"dist/*.js",
17+
"dist/*.d.ts",
18+
"dist/index.html",
1719
"README.md",
1820
"LICENSE"
1921
],
2022
"scripts": {
2123
"clean": "rm -rf dist",
2224
"build": "npm run clean && npm run build-dist",
2325
"build-dist": "webpack --progress",
26+
"build-prod": "npm run clean && NODE_ENV=production webpack --progress",
2427
"start": "webpack serve --open",
25-
"prepublishOnly": "npm run build"
28+
"prepublishOnly": "npm run build-prod"
2629
},
2730
"repository": {
2831
"type": "git",

0 commit comments

Comments
 (0)