Skip to content

1. SolidOS know how

Jump to bottom
Alain Bourgeois edited this page Mar 29, 2022 · 8 revisions

The basic instructions for running setting up SolidOS and much more can be found on the SolidOS readme.

Note: We are trying our best to keep this documentation up to date. If you see something outdated we invite you to make a ticket over at SolidOS GitHub issues.

How to contribute

How to make changes on repos

As a newcomer, you do not have direct access to the repos. In this case, you can still contribute through Pull Requests (PRs). First, navigate to the repo you want to work on and create a fork. Make your changes on your fork and then create a PR. We will be notified and you will receive feedback on your changes. For more details on how to do this, visit the GitHub documentation which explains it much better than we ever could.

If you do have direct access to the repos, it is usual to create a branch for your changes and then a PR. A PR helps you receive feedback and lets us know easily about any changes to the code. Read more about Pull Requests over at the GitHub documentation.

Dealing with GitHub branches

Steps to setup/run SolidOS using repos with different branches

If you only have to change in one or a few repositories

The first few steps (1-4) are also included in the main documentation mentioned above.

  1. Clone the SolidOS repo.
  2. Run the setup in the solidos project folder.
    npm run setup
  3. Double-check the setup completed correctly by running the watch.
    npm run watch
  4. Add any other pane or repo that will be modified. See the example below that pulls in the solid-logic repo.
    npm run add solid-logic or npm run add <git repo URL>
  5. Within the repo that should use a different branch, pull the desired branch. See the example below.
    cd workspaces/solid-ui && git checkout <branch-name>
  6. Once that has been successfully run the following command from the main SolidOS directory.
    npx lerna bootstrap --force-local
  7. Lastly, the watch from Step 3 can be run again and SolidOS should be up and running.

Note: In case the change does not work, maybe a node cache clear will help with npm cache clean --force or/and npm start -- --reset-cache.

Note: Once these steps have been followed changes can be made inside any workspaces/repo-name library or pane and the change should be immediately shown in SolidOS. Changes to node-solid-server are the only exception. In this case, SolidOS may need to be restarted.

If you need to change branch for more repositories at the same time

Follow the steps from (1-4) mentioned above. Inside SolidOS there is a script that switches branches: https://github.com/solid/solidos/blob/main/scripts/switch-branch. inside the script, you can see that it ONLY switches branches of the main repos "rdflib", "solid-ui", "solid-panes", "mashlib", "node-solid-server". If you need any other repo to be switched you can simply add it to the script and then run the script with npm switchBranch <branch-name>. Please note, if a repo does not have such a that repo will stay on the branch it currently is on. Make sure to read the output messages to check if it was successful or not.

How to add a missing package to SolidOS

When setting up SolidOS, it automatically pulls into workspaces the repos for rdflib, node-solid-sever, mashlib, solid-panes, and solid-ui. If a package is missing, such as profile-pane, you can simply add it using the add script as detailed next.

Add dependency

You can add missing packages to your SolidOS local workspaces as follows:

npm run add <name-of-repo>

If there is a package that is not mapped (part of the script already) you need to manually give the URL to the Git repo.

npm run add <name-of-repo> <git-url-of-repo>

Remove dependency

This removes a package and cleans up dependencies.

npm run delete <name-of-repo>

Debugging panes/repos standalone (without running whole SolidOS)

Debugging solid-panes using Solid Pane Tester

The Solid Pane Tester is a powerful setup for developing the full stack, from rdflib, to solid-ui, to solid-panes, to mashlib, to node-solid-server. If you are just developing a pane then you will probably find the Solid Pane Tester more useful. There, you will be able to see the effect of your changes in 5 seconds, whereas a full recompile takes more than 5 minutes. You can also just run the pane tester within this repository, at workspaces/solid-panes/dev/.

Debugging solid-ui using Storybook

To debug a component from solid-ui in isolation, when you do not need the surrounding solid-pane, you can run storybook in the solid-ui repository.

Debugging solid-ui using Solid Pane Tester

To debug solid-ui within a pane, you can combine the solid-ui to solid-panes link with the Pane Tester. For instance, when debugging code from solid-ui that affects the Sharing pane, you might run npm start to set the links between the workspaces, then run npm run watch in the solid-ui workspace and use the Solid Pane Tester in the solid-panes workspace, with the Sharing pane in workspaces/solid-panes/dev/pane/, to see how your edits in solid-ui affect the Sharing pane.

Debugging rdflib using Solid Pane Tester

Run:

npm run add rdflib
cd workspaces/rdflib
npm install
npm run build:esm
cd ../..
npm start
[Ctrl+C]
cd workspaces/solid-ui
npm run build-lib

In another terminal window, run cd workspaces/solid-panes/dev/ ; npx webpack-dev-server.

Edit workspaces/solid-panes/dev/pane/ to have the pane you want to debug.

Open http://localhost:9000 and run renderPane('http://example.com/#me') in the console to check if your setup works.

Then, under workspaces/rdflib, make your change, for instance add a console.log somewhere. It should then be enough to run npm run watch in workspaces/rdflib to make your changes in rdflib appear in the browser.

You can also combine this with cd workspaces/solid-ui ; npm run watch so that you can combine edits in rdflib with edits in solid-ui, but if you're only editing rdflib, the npm run watch in workspaces/rdflib should be enough.

Other hacks and tips

The data browser hack: upgrading your browser

This refers to a specific way in which the SolidOS is deployed for users who at first only have a conventional web browser - a hypertext browser not a data browser. It is a hack -- in the original computing sense of a crafty, though not beautiful, little thing which gets the job done.

How does the data browser work?

  1. The user goes with a normal web browser to access some data object (like a to-do list).
  2. The server sees the browser doesn't understand the data natively.
  3. The server sends back a little placeholder HTML file, databrowser.html, instead of the data.
  4. The databrowser.html file loads the mashlib.js Javascript library, which can now understand the data.
  5. The mashlib.js then re-requests the original data, but accepts data formats.
  6. The server supplies the actual data of the to-do list or whatever it was.
  7. The mashlib.js code provides an editable visualization of the data.

The mashlib human interface is read-write: where the user is allowed to edit: it lets them edit the data and create new things. It is live, in that often the data browser signed up (using a WebSocket) for any changes which other users make, so users' screens are synchronized.

A major limitation of the data browser hack is that current web browsers are made to distrust any code loaded from one domain that uses data from another domain. This makes it hard, strangely complicated, and sometimes impossible to do some things.

Running SolidOS Web App(https://solid.github.io/mashlib/static/browse.html) locally

npm run startStaticOS

or (but make sure not to commit vite to package.json):

cd mashlib/dist
npm install vite
npx vite
Clone this wiki locally