FCS SRU Aggregator UI

Technologies

The frontend uses the following technologies:

• ReactJS 18.3.1
  • React Router ("library") 7.8.2 for SPA routing
  • React Query 5.85.9 with Axios 1.11.0 for web requests
  • react-i18next 15.7.3 and i18next 25.4.2 for translation support, with i18next-resources-to-backend 1.2.1 for dynamic resource loading
• Bootstrap 5.3.8 with Bootstrap Icons 1.13.1, integration with React Bootstrap 2.10.10
• microfuzz 1.0.0 for fuzzy searching
• react-slugify 4.0.1 for generating hash urls
• PrismJS 1.29.0 for syntax highlighting
• ANTLR4ng 3.0.16 for syntax parsing (visual query builder, syntax validation)
• Zustand 5.0.8 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 7.1.4 with plugins
  • estree-walker 3.0.3 and magic-string 0.30.18 for custom source code transformation (import rewriting, bundle building)
  • picomatch 4.0.3 for filename filters in output control
• TypeScript 5.9.2 with @types/* definitions
• ESLint 9.34.0 with plugins
• simple-git 3.28.0 for source code information

Features

• Modern, mobile-friendly, dark-mode, accessibility (ARIA) support
• Single¹ SPA bundle for easy integration
• Various usability features like fuzzy filtering, tooltips, ...
• Input support with query syntax highlighting and visual query builders (FCS-QL, LexCQL)

¹ 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 22+ (due to node:fs -> globSync)

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 transform dynamic imports into static imports and bundle everything into the main bundle!

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.

Environment variables allow further configurations of the build. They can be set in the .env.local file or prefixed to the command. Environment variables are evaluated in the vite.config.ts file and the related settings (import.meta.env.) can also be modified there but this is not recommended as it makes it more difficult to update the source code.

• Disable language switcher (use only one locale): VITE_LOCALES='["en"]' npm run build
• Disable the visual query builder: VITE_FEATURE_QUERY_BUILDER=false npm run build

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
  • 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.

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
• APP_TITLE: application title, by default Content Search
• APP_TITLE_HEAD: application title, will be used for HTML HEAD title tag, by default FCS Aggregator – Content Search
• MATOMO_TRACKING_PARAMS: matomo tracking parameters, see section about FEATURE_TRACKING_MATOMO above

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,
  },
})