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
Repository settings
Pre-release FOLIO modules are published to our folioci package repository, apart from publicly available npm . To install pre-release dependencies, you will need to configure your package manner to install @folio-scoped packages from the folioci repository by executing this in a command prompt:
$ yarn config set @folio:registry https://repository.folio.org/repository/npm-folioci/
Dev Workspace
For the best developer experience, it’s advisable to do development within a yarn workspace. Your workspace will need to include a FOLIO platform as well as a clone of your own ui-module. A sample workspace package.json for convenience can be as follows:
{
"private": true,
"workspaces": [
"*"
],
"dependencies": {
"yarn": "^1.22.17"
}
}
Set Okapi URL
Typescript
Linting
Testing
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)