UI Modules and the FOLIO Platform

What is a UI Module?

A FOLIO UI Module is one piece of several modular pieces within a platform. It represents a vertical slice of the functionality that a Library will require from its ILS. As a software developer, it’s very easy to view your FOLIO App as THE entire app, but that is not the realistic view of things. Your FOLIO module will be served alongside other FOLIO modules and must be created in a way that is considerate of inter-module relationships and its functionality as part of the workflows, part of the platform. Now that we’ve said that, on to more good stuff!

What is Okapi (for frontend developers)

What Stripes Provides

Platform Provided Dependencies

These are dependencies that may or may not be used in your module, but are common within the platform. These are singleton dependencies, so its necessary that they’re only added to the bundle from one primary, dependent source (the platform!) They should be listed as both peerDependencies and devDependencies (for testing) in your ui-module’s package.json

React Router/React Router DOM

Provides our general routing infrastructure.

Form Library

Provides a consistent source of implementation for various form-related concerns such as validation and tracking a form state. As of Quesnelia release, there is still usage of redux-form and react-final-form within the system, but these projects have decreased in maintainer responsibility. react-hook-form is the recommended package for new form development - but it isn’t provided by the platform yet. Stay tuned!!

Date/Time Library

As of Quesnelia release, DayJS (source) is available from @folio/stripes/components as a pre-extended export. See Date/time utilities documentation for more information.

Data Fetching

For API calls, we provide ky, and react-query v3. A global react-query QueryClientProvider wraps the module container; modules must not implement their own. @folio/stripes/core exports useOkapiKy (source) and withOkapiKy (source) which decorate API requests with the options and headers necessary to interact with the API gateway, Okapi. Requests to non-FOLIO APIs should use ky or fetch.

Zustand

Zustand v4 is a global state management solution.

Development setup

1. Configure yarn to point to the dev repository: $ yarn config set @folio:registry https://repository.folio.org/repository/npm-folioci/

2. Create a simple yarn workspace.

3. Clone a platform as well as your ui-module code into the workspace.

4. Add your ui module to the platform’s package.json and stripes.config.js

5. Set the okapi URL in stripes.config.js.

6. In the platform directory, run your project with yarn stripes serve stripes.config.js

https://folio-org.atlassian.net/wiki/spaces/DEV/pages/192970772 Provides a more elaborate description of these steps.



This document is a work-in-progress!
Sections below to be filled out soon!

Navigation/Routing

Settings

Fetching Data

What Stripes Provides

OkapiKy

React Query

Caching - Namespacing

Presenting Data

Stripes-components

Common Components

Panes

LayoutGrid

MCL

Form controls

Conditional presentation

IfPermission

IfInterface

Common UI Patterns

3-pane layout

Settings

Plugins

Forms

Feedback

Validation

Callout/ Callout Context

Dates/Times

Styles

CSS-Modules

PostCSS Stack

Handling Changes

Versioning - What constitutes a breaking change?

Contributing

PR Comments

Your PR Comments are a very important part of the contribution process! Good comments will clearly express the intentions of the code and allow reviewers to provide the best direction possible so that we can merge consistent, clean code. Here’s a few items that a good PR comment will have:

• A link to the applicable Jira ticket.

• Problem statement - what problem does your code resolve? Is there a buggy behavior? Was logic implemented incorrectly before? How so?

• Approach - How did you go about resolving the problem? Any uncommon knowledge as to why your solution resolves the issue.

• Questions, target areas for review - are there any areas of the code that reviewers should focus on?

Jira ticket association

Your Jira ticket ‘UIEXAMPLE-###’ should be in at least two places.

• Your Branch Name - this will associated it with the ‘Development’ fields on the Jira ticket via the JIRA-Github integration. This allows PO’s and maintainers to easily track progress of the work.

• A link to the Jira ticket in your PR comment (as mentioned above)

Deprecations/Migrations

SearchAndSort

Stripes-connect

Redux-form/React Final Form

Moment