FCS SRU Aggregator UI

Technologies

The frontend uses the following technologies:

• ReactJS 18.3.1
  • React Router ("library") 7.0.2 for SPA routing
  • React Query 5.62.7 with Axios 1.7.9 for web requests
• Bootstrap 5.3.3 with Bootstrap Icons 1.11.3, integration with React Bootstrap 2.10.6
• microfuzz 1.0.0 for fuzzy searching
• PrismJS 1.29.0 for syntax highlighting
• ANTLR4ng 3.0.14 for syntax parsing (visual query builder, syntax validation)
• Zustand 5.0.2 for state management of external bundle configuration
• React Helmet (Async Fork) 2.0.5 for webpage meta information

For development and building a few additional dependencies are required:

• Vite 6.0.1 with plugins
• TypeScript 5.6.2 with @types/* definitions
• ESLint 9.15.0 with plugins

Features

• Modern, mobile-friendly, dark-mode, accessibility (ARIA) support
• Single¹ SPA bundle for easy integration
• Various usability features like fuzzy filtering, ...

¹ The build process will generate multiple JS and CSS files to split application code from vendor code but those files only need to be included as scripts/styles in a static index.html page without requiring any complicated server setup.

Requirements

• Node 18+ (?)

How to deploy

Building

Running the following command will create a fully static bundle that is ready to be deployed. The build artifacts will be placed into the dist/ folder. The index.html file is the entry point with all dependencies (scripts, styles, images and other assets) in the lib/ subfolder.

npm run build

To generate a single bundle build (one script and one style file, with picture assets) use the following command. This will also disable dynamic imports.

npm run build:bundle

An overview over all the dependency modules and code files will be generated by rollup-plugin-visualizer and can be found in either bundle-visualization.html or dist/bundle-visualization.html depending on the plugin configuration.

Configuration

The bundle can be pre-configured by adjusting the import.meta.env. constants found in the vite.config.ts configuration file.

• "branding" related configs:
  • HEAD_TITLE: the base application title for the browser
  • CONTACT_ADDRESS: the contact email address for users to get in contact with
  • TERMS_AND_DISCLAIMER_ADDRESS: the webpage with information about the website like disclaimer, imprint, GDPR, ...
  • CANONCIAL_URL: the canonical URL to the application (head meta information), unused for now?
• deployment base configuration
  • DEPLOY_PATH: the (sub-)path the application is served from, by default / for the root
  • API_URL: the backend FCS SRU Aggregator REST API endpoint, required!
  • VALIDATOR_URL: the URL to the FCS Endpoint Validator
• optional features
  • SHOW_SEARCH_RESULT_LINK: boolean, whether to display a semi-permanent search results link, use only for development to avoid confusion
  • FEATURE_TRACKING_MATOMO: boolean, whether to include Matomo/Piwik tracking/statistics calls
    • FEATURE_TRACKING_MATOMO_PARAMS: parameters for tracking setup, set with JSON.stringify({}) where the parameter object {} should contain the following entries:
      • siteId: number, required, for setSiteId
      • trackerUrl: URL for tracking server, required, for setTrackerUrl, likely something like <baseUrl>/matomo.php
      • enableLinkTracking: boolean, optional, by default true, can be disabled
      • domains: string[], optional, can be a list of to be considered "local" domain names, for setDomains
      • userId: string, optional, will be hashed with cyrb53, for setUserId
      • srcUrl: URL for JS script source to load Matomo/Piwik script, required, likely something like <baseUrl>/matomo.js
      • NOTE: if not set or any required value is likely invalid, then tracking will not be configured!
  • FEATURE_QUERY_BUILDER: boolean, whether to include a Visual Query Builder (FCS-QL). If not specified (or explicitely set to true) then it will be excluded from the generated build. Enabling it, multiple output files will be generated, a vendor/antlr.js chunk as well as *-query-builder-*.{js,css} files that will be dynamically loaded when the UI requires them.
  • FEATURE_LAZY_LOADING: boolean, whether to enable lazy loading of some optional component using dynamic imports, if not set to true (truthy value) then all optional components will be included statically (might be tree-shaken).

Runtime configuration can be set using the window.MyAggregator object and needs to be included before the application script fcs-sru-aggregator-ui-X.Y.Z.js is being loaded. They are completely optional but can be used to override bundle configuration.

• DEPLOY_PATH: the basename of the application, e.g. if deployed on some subpath like example.org/aggregator/ use /aggregator, by default /
• API_URL: the base URL to the FCS SRU Aggregator REST API, e.g. https://contentsearch.clarin.eu/rest/
• VALIDATOR_URL: the base URL to the FCS Endpoint Validator, e.g. https://www.clarin.eu/fcsvalidator/
• SHOW_SEARCH_RESULT_LINK: boolean (true/false) for whether to display a semi-permanent link to search results using the internal searchID

Development

Based on React + TypeScript + Vite template (npm create vite@latest), a minimal setup to get React working in Vite with HMR and some ESLint rules. Uses the @vitejs/plugin-react uses Babel plugin for Fast Refresh.

For local testing run:

npm run dev

Update dependencies

• Check possible upgrades with npx npm-check-updates
• Check system information (for bug reports etc.) npx envinfo --system --npmPackages --binaries --browsers

Expanding the ESLint configuration (TODO)

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

• Configure the top-level parserOptions property like this:

export default tseslint.config({
  languageOptions: {
    // other options...
    parserOptions: {
      project: ['./tsconfig.node.json', './tsconfig.app.json'],
      tsconfigRootDir: import.meta.dirname,
    },
  },
})

• Replace tseslint.configs.recommended to tseslint.configs.recommendedTypeChecked or tseslint.configs.strictTypeChecked
• Optionally add ...tseslint.configs.stylisticTypeChecked
• Install eslint-plugin-react and update the config:

// eslint.config.js
import react from 'eslint-plugin-react'

export default tseslint.config({
  // Set the react version
  settings: { react: { version: '18.3' } },
  plugins: {
    // Add the react plugin
    react,
  },
  rules: {
    // other rules...
    // Enable its recommended rules
    ...react.configs.recommended.rules,
    ...react.configs['jsx-runtime'].rules,
  },
})