https://github.com/clarin-eric/fcs-sru-aggregator-ui

Singe Page Application Frontend for CLARIN FCS SRU Aggregator
https://github.com/clarin-eric/fcs-sru-aggregator-ui

bootstrap5 fcs federated-content-search reactjs

Last synced: 5 months ago
JSON representation

Singe Page Application Frontend for CLARIN FCS SRU Aggregator

• Host: GitHub
• URL: https://github.com/clarin-eric/fcs-sru-aggregator-ui
• Owner: clarin-eric
• License: gpl-3.0
• Created: 2025-01-15T13:30:18.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-11-18T12:56:50.000Z (7 months ago)
• Last Synced: 2025-11-18T15:56:44.434Z (7 months ago)
• Topics: bootstrap5, fcs, federated-content-search, reactjs
• Language: TypeScript
• Homepage: https://clarin-eric.github.io/fcs-sru-aggregator-ui/
• Size: 1.84 MB
• Stars: 0
• Watchers: 8
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: COPYING

Awesome Lists containing this project

README

          
# FCS SRU Aggregator UI

## Technologies

The frontend uses the following technologies:

- [ReactJS](https://18.react.dev/) 18.3.1

  - [React Router](https://reactrouter.com/start/library/installation) ("library") 7.12.0 for SPA routing

  - [React Query](https://tanstack.com/query/latest) 5.90.16 with [Axios](https://github.com/axios/axios) 1.13.2 for web requests

  - [react-i18next](https://react.i18next.com/) 16.5.1 and [i18next](https://www.i18next.com/) 25.7.4 for translation support, with [i18next-resources-to-backend](https://github.com/i18next/i18next-resources-to-backend) 1.2.1 for dynamic resource loading

- [Bootstrap](https://getbootstrap.com/) 5.3.8 with [Bootstrap Icons](https://icons.getbootstrap.com/) 1.13.1, integration with [React Bootstrap](https://react-bootstrap.netlify.app/) 2.10.10

- [microfuzz](https://github.com/Nozbe/microfuzz) 1.0.0 for fuzzy searching

- [react-slugify](https://github.com/martpie/react-slugify) 4.0.1 for generating hash urls

- [PrismJS](https://github.com/PrismJS/prism) 1.29.0 for syntax highlighting

- [ANTLR4ng](https://github.com/mike-lischke/antlr4ng) 3.0.16 for syntax parsing (visual query builder, syntax validation)

- [Zustand](https://github.com/pmndrs/zustand) 5.0.9 for state management of external bundle configuration

- [React Helmet (Async Fork)](https://github.com/staylor/react-helmet-async) 2.0.5 for webpage meta information

For development and building a few additional dependencies are required:

- [Vite](https://vite.dev/) 7.3.1 with plugins

  - [estree-walker](https://github.com/Rich-Harris/estree-walker) 3.0.3 and [magic-string](https://github.com/rich-harris/magic-string) 0.30.21 for custom source code transformation (import rewriting, bundle building)

  - [picomatch](https://github.com/micromatch/picomatch#globbing-features) 4.0.3 for filename filters in output control

- [TypeScript](https://www.typescriptlang.org/) 5.9.3 with `@types/*` definitions

- [ESLint](https://eslint.org/) 9.39.2 with plugins

- [simple-git](https://github.com/steveukx/git-js) 3.30.0 for source code information

## Features

- Modern, mobile-friendly, dark-mode, accessibility (ARIA) support

- Single[¹](#footnote-1) 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/`](dist/) folder. The `index.html` file is the entry point with all dependencies (scripts, styles, images and other assets) in the `lib/` subfolder.

```bash

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!

```bash

npm run build:bundle

```

An overview over all the dependency modules and code files will be generated by [rollup-plugin-visualizer](https://github.com/btd/rollup-plugin-visualizer) and can be found in either [`bundle-visualization.html`](bundle-visualization.html) or [`dist/bundle-visualization.html`](dist/bundle-visualization.html) depending on the plugin configuration.

Environment variables allow further [configurations](#configuration) of the build. They can be set in the [`.env.local`](.env.local) file or prefixed to the command. Environment variables are evaluated in the [`vite.config.ts`](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`](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 `/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](https://stackoverflow.com/a/52171480/9360161), for `setUserId`

      - `srcUrl`: URL for JS script source to load Matomo/Piwik script, required, likely something like `/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.js`](dist/lib/) 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](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) plugin for Fast Refresh.

For local testing run:

```bash

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:

```js

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](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:

```js

// 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,

  },

})

```