{"id":13364,"library":"javascript-solid-server","title":"JavaScript Solid Server","description":"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.","status":"active","version":"0.0.136","language":"javascript","source_language":"en","source_url":"https://github.com/JavaScriptSolidServer/JavaScriptSolidServer","tags":["javascript","solid","ldp","linked-data","decentralized","activitypub","fediverse","nostr"],"install":[{"cmd":"npm install javascript-solid-server","lang":"bash","label":"npm"},{"cmd":"yarn add javascript-solid-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add javascript-solid-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional storage backend for scaling JSON-LD data; used via the `/db/` route.","package":"mongodb","optional":true}],"imports":[{"note":"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.","wrong":"const { createServer } = require('javascript-solid-server');","symbol":"createServer","correct":"import { createServer } from 'javascript-solid-server';"},{"note":"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.","wrong":"import SolidServer from 'javascript-solid-server';","symbol":"SolidServer","correct":"import { SolidServer } from 'javascript-solid-server';"},{"note":"This is a TypeScript type definition for configuring the server. It should be imported using `import type` to avoid bundling unnecessary runtime code.","wrong":"import { ServerOptions } from 'javascript-solid-server';","symbol":"ServerOptions","correct":"import type { ServerOptions } from 'javascript-solid-server';"}],"quickstart":{"code":"# Install JSS globally\nnpm install -g javascript-solid-server\n\n# Start the server with common options (e.g., enable Identity Provider, Mashlib UI, Content Negotiation, Git, Nostr)\njss start --port 8443 --idp --mashlib --conneg --git --nostr\n\n# Wait for the server to start (e.g., at https://localhost:8443 or http://localhost:4443 if SSL is not configured)\n\n# Create a new pod for 'alice' (replace with your server's actual port and domain if different)\ncurl -X POST http://localhost:4443/.pods \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"alice\"}'\n\n# Read content from Alice's public directory (adjust port/path if needed)\ncurl http://localhost:4443/alice/public/\n\n# Write data to Alice's pod (requires authentication token, replace YOUR_TOKEN and adjust content)\n# Note: You would typically get a Bearer token after logging in via the IdP (e.g., at https://localhost:8443)\ncurl -X PUT http://localhost:4443/alice/public/data.json \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type\": \"application/ld+json\" \\\n  -d '{\"@id\": \"#data\", \"http://example.org/value\": 42}'","lang":"bash","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"JSS 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"Security 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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`).","message":"Running the server on Node.js versions older than 18.0.0 will result in errors due to engine requirements.","severity":"gotcha","affected_versions":"<=0.0.136"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Stop the conflicting process or start JSS on a different port using `jss start --port <NEW_PORT_NUMBER>`.","cause":"Another process is already using the specified port (e.g., 8443 or 4443).","error":"Error: listen EADDRINUSE: address already in use :::8443"},{"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.","cause":"Incorrect or missing authentication token, or insufficient permissions defined in Web Access Control (.acl) files.","error":"401 Unauthorized / 403 Forbidden when accessing pod resources"},{"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.","cause":"The `javascript-solid-server` package was not installed globally or is not in your system's PATH.","error":"Cannot find module 'jss'"},{"fix":"Provide a valid JSON body with a 'name' field, e.g., `-d '{\"name\": \"yourpodname\"}'`.","cause":"When creating a pod via `POST /pods`, the JSON payload is missing the required `name` field for the new pod.","error":"Failed to create pod: Status 400 Bad Request - 'name' field is required in JSON payload"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"jss","cli_version":null}