Registry / web-framework / javascript-solid-server

javascript-solid-server

library0.0.136jsnpmunverified

The JavaScript Solid Server (JSS) is a high-performance, feature-rich implementation of the Solid protocol, designed for decentralized web applications. Currently at version 0.0.136, it is under active and rapid development, implying frequent updates and potential breaking changes as it progresses towards a stable 1.0 release. JSS differentiates itself by being JSON-LD native for data storage by default, offering optional Turtle conversion via content negotiation. Its comprehensive feature set includes a built-in Solid-OIDC Identity Provider, Web Access Control, WebSocket Notifications for real-time updates, multi-user pod support, and unique integrations like a Git HTTP backend for version control, a Nostr Relay for decentralized social networking, ActivityPub for Fediverse federation, and even HTTP 402 Payments for monetization. It also supports optional MongoDB storage for scalability and various development tools like a WebRTC signaling server, a decentralized tunnel proxy, and a WebSocket terminal, making it a highly versatile platform for building and hosting Solid pods.

web-framework http-networking database auth-security serialization

npm install javascript-solid-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JAVASCRIPT-SOLID-S

javascript-solid-server

web-frameworkjavascriptv0.0.136

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createServer

✓ import { createServer } from 'javascript-solid-server';

✗ const { createServer } = require('javascript-solid-server');

Primary programmatic entry point for creating and configuring a JSS instance. While CommonJS `require` might technically work in some Node.js environments, ESM `import` is the idiomatic and recommended approach for modern Node.js and TypeScript. The documentation primarily focuses on CLI usage for starting the server.

SolidServer

✓ import { SolidServer } from 'javascript-solid-server';

✗ import SolidServer from 'javascript-solid-server';

This named export provides access to the SolidServer class for advanced programmatic control or extension. Avoid default import as it's not the primary export.

ServerOptions

✓ import type { ServerOptions } from 'javascript-solid-server';

✗ import { ServerOptions } from 'javascript-solid-server';

This is a TypeScript type definition for configuring the server. It should be imported using `import type` to avoid bundling unnecessary runtime code.

Demonstrates global installation, starting the JSS server with key features enabled, creating a new user pod, and performing basic read/write operations via cURL, highlighting the CLI-first interaction model.

# Install JSS globally npm install -g javascript-solid-server # Start the server with common options (e.g., enable Identity Provider, Mashlib UI, Content Negotiation, Git, Nostr) jss start --port 8443 --idp --mashlib --conneg --git --nostr # Wait for the server to start (e.g., at https://localhost:8443 or http://localhost:4443 if SSL is not configured) # Create a new pod for 'alice' (replace with your server's actual port and domain if different) curl -X POST http://localhost:4443/.pods \ -H "Content-Type: application/json" \ -d '{"name": "alice"}' # Read content from Alice's public directory (adjust port/path if needed) curl http://localhost:4443/alice/public/ # Write data to Alice's pod (requires authentication token, replace YOUR_TOKEN and adjust content) # Note: You would typically get a Bearer token after logging in via the IdP (e.g., at https://localhost:8443) curl -X PUT http://localhost:4443/alice/public/data.json \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type": "application/ld+json" \ -d '{"@id": "#data", "http://example.org/value": 42}'

jss --version

Debug

Known issues

breakingThe package is currently in early development (version 0.0.x), meaning frequent breaking changes can occur between minor versions. APIs, configuration options, and default behaviors are subject to change without major version increments.

fix

Always refer to the latest official documentation and `CHANGELOG` before upgrading. Test thoroughly in development environments. Consider pinning exact versions in `package.json` for stability.

affects: >=0.0.1

gotchaJSS is 'JSON-LD native', meaning it stores and processes JSON-LD by default. While it offers Turtle (RDF) conversion via `--conneg`, developers primarily expecting Turtle interaction might face unexpected behavior if `Content-Type` headers are not correctly managed or `--conneg` is not enabled.

fix

Explicitly set `Content-Type: text/turtle` or `application/n-quads` in requests when interacting with RDF, or ensure the `--conneg` flag is used when starting the server if Turtle negotiation is desired. Default to `application/ld+json` for JSON-LD data.

affects: >=0.0.1

gotchaSecurity configuration, especially around Web Access Control (WAC) files (`.acl`), Solid-OIDC (Identity Provider), and DPoP, is crucial. Misconfigurations can lead to unauthorized data access or identity impersonation. The server acts as an IdP, requiring careful setup.

fix

Thoroughly review the authentication and authorization documentation. Use strong passwords for IdP accounts. Regularly audit `.acl` files and ensure DPoP is correctly implemented for client applications. Do not expose administrative interfaces publicly without robust security measures.

affects: >=0.0.1

gotchaRunning the server on Node.js versions older than 18.0.0 will result in errors due to engine requirements.

fix

Ensure your Node.js environment is version 18.0.0 or higher. Use a Node.js version manager like `nvm` to easily switch and manage Node.js versions (`nvm install 18 && nvm use 18`).

affects: <=0.0.136

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::8443

Another process is already using the specified port (e.g., 8443 or 4443).

fix

Stop the conflicting process or start JSS on a different port using `jss start --port <NEW_PORT_NUMBER>`.

401 Unauthorized / 403 Forbidden when accessing pod resources

Incorrect or missing authentication token, or insufficient permissions defined in Web Access Control (.acl) files.

fix

Ensure you have a valid Bearer token obtained from the Solid-OIDC Identity Provider. Verify that the `.acl` file for the resource grants the authenticated user/agent the necessary read/write permissions.

Cannot find module 'jss'

The `javascript-solid-server` package was not installed globally or is not in your system's PATH.

fix

Install the package globally using `npm install -g javascript-solid-server`. If already installed, ensure your system's PATH includes the global `node_modules` bin directory.

Failed to create pod: Status 400 Bad Request - 'name' field is required in JSON payload

When creating a pod via `POST /pods`, the JSON payload is missing the required `name` field for the new pod.

fix

Provide a valid JSON body with a 'name' field, e.g., `-d '{"name": "yourpodname"}'`.

Upgrade

Version history

0.0.136latest on npm

Audit

Dependencies

mongodboptionalOptional storage backend for scaling JSON-LD data; used via the `/db/` route.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/JavaScriptSolidServer/JavaScriptSolidServer ↗

packagehttps://www.npmjs.com/package/javascript-solid-server ↗

homepagehttps://solidproject.org ↗