Sophys Web

Overview

Sophys Web is a monorepo for beamline web apps designed to integrate with the SOphYS ecosystem (Sirius Ophyd and blueskY utilitieS), providing user interfaces for experiment control and data acquisition. It includes multiple applications plus shared packages (UI components, API clients, hooks, and utilities) to promote reuse across the workspace and a built-in generator for scaffolding new apps.

Note

This project is under heavy development and new features and apps are being added frequently.

Built with

• Turborepo
• Next.js
• React
• TypeScript
• Tailwind CSS
• shadcn-ui

Existing apps

• spu-ui: A web application for the SAPUCAIA beamline at LNLS.
• qua-ui: A web application for the QUATI beamline at LNLS.

Development

Setup

# Install dependencies
pnpm i

# Configure environment variables
# There is an `.env.example` in the root directory you can use for reference
cp .env.example ./apps/spu-ui/.env

Note

One must copy the .env.example file to .env and configure the environment variables accordingly for each app in the apps directory, because each app has its own environment variables and can be configured and deployed independently.

Third-party dependencies

This project depends on having an external server running the bluesky http-server.

Some packages may require additional external services to be running, such as a PVWS server for real-time data updates via WebSockets or a redis instance. These dependencies will be documented in the README files of the respective apps or packages that require them.

Running the development server

To run the development server, use the following command:

pnpm dev

This will start the spu-ui app on http://localhost:3000.

Local CI

To run the CI tests locally, use the following command:

pnpm local-ci

How to build a new app

To build a new app from scratch and take advantage of the shared packages and utilities, do the following:

Set up node and pnpm

This project requires node with version 22.14.0 or higher and pnpm with version 9.6.0 or higher.

If you don't have node and pnpm installed, go to the Node.js website and follow the instructions to install Node.js with pnpm for your operating system.

Set up the repository

First, set up a fork of this repository on GitHub and clone it to your local machine.

Then, install the dependencies:

pnpm i

This will install all the dependencies for the monorepo and the apps in the apps directory.

Create a new app using the generator

To scaffold a new app, use the turbo generate command:

pnpm turbo generate app

This will prompt you for the name of the app and create a new directory in the apps directory with the name of the app.

Configure environment variables

[!NOTE] The new app will generate a small set of default environment variables in a .env file, such as BLUESKY_HTTPSERVER_URL and AUTH_SECRET. Please make sure to set the correct values for these variables in the .env file.

Run the app in development mode

To run the app in development mode, use the following command:

pnpm dev --filter=@sophys-web/<new-app-name>

This will start the app on http://localhost:3000 by default.

Note

The --filter flag is used to run only the app that you just created. If you want to run all the apps, you can use the pnpm dev command without the --filter flag.

Install new external dependencies to an app

When you are developing your new app, you will probably want to install external dependencies to your app other than the ones that are pre-installed. Since this project is JavaScript and Node.js based, we can search for packages in the npm registry, which is "the largest software registry in the world" and the epicenter of JavaScript code sharing.

Full example

Let's imagine you decided that your project needs the nanoid package, because you saw an example of a code that creates unique ids with it, like the following snippet:

import { nanoid } from "nanoid";

model.id = nanoid(); //=> "V1StGXR8_Z5jdHi6B-myT"

So, naturally, your next step was finding the package in the npm registry: nanoid.

There you noticed that the package is in a version bigger than 5, has more than 50M weekly downloads, has 0 dependencies and the docs say that it does what you want it to do. So you decide you trust it and will install it.

Warning

In the Install instructions for the package in the npm registry, you will see only the suggestion to use the npm package manager, but this project requires pnpm as the package manager, so you will need - among other things - to replace the npm for pnpm in the install command.

We also need to consider that we are working in a monorepo that manages multiple apps and internal packages that have their own dependencies, so we need to be careful about where we want this new dependency installed.

In our example, we want to install this package to an app that exists in the apps/ directory of this monorepo. Let's say that the name of our app (defined in its own package.json file) is @sophys-web/test-ui. So, for this case, the full command to add nanoid as a dependency in this app is:

pnpm add --filter @sophys-web/test-ui nanoid

Generally speaking, to add any dependencies to an app or an internal package in this project, the command should be:

pnpm add --filter @sophys-web/<app-name> <package-name>

You can read more about the options for managing dependencies on this monorepo in the turborepo docs on managing dependencies.

Deployment

With Docker

To deploy the app with Docker, you can use the provided Dockerfile in the app's directory. The Dockerfile is set up to build the app and run it in a production environment. To build the Docker image, run the following command in the root directory of the monorepo:

docker build -t sophys-web-qua-ui -f apps/qua-ui/Dockerfile .

To run the Docker container, use the following command:

docker run -d -p 3000:3000 sophys-web-qua-ui