Writing Solid applications with React

Submitted by khoward on Wed, 01/23/2019 - 19:44

Getting Started

The easiest way to get started developing Solid with React is to use the Solid-React Yeoman Generator.

Prerequisites

Administrator Privilege

You will need administrative privilege on your local computer to install the Generator and prerequisites. Depending upon your operating system:

  • Mac:
    1. Prefix the command lines to be executed with sudo.
    2. You will be prompted for the Administrator password. Refer to: https://support.apple.com/en-us/HT202035.
  • Windows:
    1. Type cmd in the search bar.
    2. Right click on "Command prompt" and select "Run as Administrator".

npm and Yeoman

To install the Generator, you will need both npm and Yeoman if you don't already have them.

  1. npm makes it easy for JavaScript developers to share and reuse code, and makes it easy to update the code that you are sharing. We recommend the use of a node version manager (nvm) to manage multiple versions of npm, and will also set up your npm permissions properly. To install using a nvm, follow the instructions here.
  2. Yeoman provides a generator ecosystem to scaffold complete projects, installing all the basic files, folders, and dependencies that you will need to start coding right away. If you’re new to Yeoman, you can check out the helpful Yeoman Getting Started guide. You can install Yeoman using the following command: 
    • npm install -g yo

Installation

The code for the Solid-React Generator can be found on github: https://github.com/inrupt/generator-solid-react. To install the Generator, in a command line window follow these steps:

  1. Execute:

    • npm install -g @inrupt/generator-solid-react

Usage

Once the Generator is installed, you can create a new application with just a few steps:

  1. Navigate to the root project folder you want the application to live in.

  2. Execute:

    • yo @inrupt/solid-react

  3. You will prompted to set:

    • An application / folder name.

    • A version number.

    • Whether the application is private or public.

  4. React libraries and dependencies are then installed, together with a sample application.

Note: We have noticed an error is sometimes thrown when the Generator tries to install one of the dependencies of application. If this occurs, try installing Git and then rebuilding your application.

You can start the sample application by navigating to the newly created directory and executing:

  • npm run start

Welcome to Solid!

Dependencies

Below is a high-level list of dependencies for this application. It is not a comprehensive list by any means, but hits the major dependencies and gives a brief description of what they are.

What the Sample Application Does

This sample application is a basic profile viewing and editing application. It consists of only a few pages and routes. There’s a login page and a welcome page displaying basic profile information.

You can login to see how authentication works, and view your profile information. It also demonstrates some of the best practices of Solid application development, including how to use some of the provided libraries.

The goal of the sample application is to show the authentication process, data manipulation inside of Solid, and to provide an example of how to do it within the React ecosystem.

Code Workflow

Step 1: Registration

The first thing your users will need is a POD on a Solid server. We have provided a registration link and workflow in the generated application, which integrates with Solid server. Out of the box, only a few Providers are supported for now, but you can easily add more.

To get started right away, you can register for a POD with an existing Solid Provider here.

Step 2: Login

Once registered for a POD with a Solid Provider, your user can login using that Provider. The sample application includes a functional login workflow. By default, the page will redirect to the Provider’s login page, then return to a URL provided in the login call. In our example, it returns us to the welcome page.

Once login is complete, a localStorage item is created with the user’s token. In the React application example, we provide private routes against this localStorage object being missing.

Step 3: Welcome/View Profile

After the user is successfully authenticated, the /welcome route will load. This is a landing page that contains some explanation, and is intended only as an example of how to read data using the LDFlex library.

Code Structure

The code structure should be familiar to React developers. It was generated with Create-React-App, and is built using Presentational / Container Components. This architecture allows the data logic to be separated from the presentation or UI layer.

We also make use of React Styled Components for further code cleanliness. Using Styled Components, we can make named Components to handle styling, so the markup is cleaner and easier to read.

Areas of Interest

Here are the most relevant files to learn more about React Solid development:

  • src/containers:

    • This folder is where most of the pages/components live. It contains components such as:

      • Login Page.

      • Registration Page.

      • Welcome Page.

  • src/services:

    • This folder contains any services required explicitly by the generated application.

    • Currently, this is only the Providers service, which is used to get a list of Providers. This is only temporary until a Provider registry exists.

  • src/utils:

    • This folder contains helpers for the generated application.

    • Examples include:

      • Styled Component helpers, for things like common media query sizes.

      • Enzyme test setup helpers.