{"id":39497010,"url":"https://github.com/clarin-eric/fcs-sru-aggregator-ui","last_synced_at":"2026-01-18T05:43:18.103Z","repository":{"id":278556107,"uuid":"917163398","full_name":"clarin-eric/fcs-sru-aggregator-ui","owner":"clarin-eric","description":"Singe Page Application Frontend for CLARIN FCS SRU Aggregator","archived":false,"fork":false,"pushed_at":"2025-11-18T12:56:50.000Z","size":1927,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-11-18T15:56:44.434Z","etag":null,"topics":["bootstrap5","fcs","federated-content-search","reactjs"],"latest_commit_sha":null,"homepage":"https://clarin-eric.github.io/fcs-sru-aggregator-ui/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clarin-eric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-15T13:30:18.000Z","updated_at":"2025-11-18T12:56:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e2484dd-1e6e-4b40-a108-fe027f5188e2","html_url":"https://github.com/clarin-eric/fcs-sru-aggregator-ui","commit_stats":null,"previous_names":["clarin-eric/fcs-sru-aggregator-ui"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/clarin-eric/fcs-sru-aggregator-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarin-eric%2Ffcs-sru-aggregator-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarin-eric%2Ffcs-sru-aggregator-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarin-eric%2Ffcs-sru-aggregator-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarin-eric%2Ffcs-sru-aggregator-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clarin-eric","download_url":"https://codeload.github.com/clarin-eric/fcs-sru-aggregator-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clarin-eric%2Ffcs-sru-aggregator-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrap5","fcs","federated-content-search","reactjs"],"created_at":"2026-01-18T05:43:18.050Z","updated_at":"2026-01-18T05:43:18.095Z","avatar_url":"https://github.com/clarin-eric.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FCS SRU Aggregator UI\n\n## Technologies\n\nThe frontend uses the following technologies:\n\n- [ReactJS](https://18.react.dev/) 18.3.1\n  - [React Router](https://reactrouter.com/start/library/installation) (\"library\") 7.12.0 for \u003cabbr title=\"Single Page Application\"\u003eSPA\u003c/abbr\u003e routing\n  - [React Query](https://tanstack.com/query/latest) 5.90.16 with [Axios](https://github.com/axios/axios) 1.13.2 for web requests\n  - [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\n- [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\n- [microfuzz](https://github.com/Nozbe/microfuzz) 1.0.0 for fuzzy searching\n- [react-slugify](https://github.com/martpie/react-slugify) 4.0.1 for generating hash urls\n- [PrismJS](https://github.com/PrismJS/prism) 1.29.0 for syntax highlighting\n- [ANTLR4ng](https://github.com/mike-lischke/antlr4ng) 3.0.16 for syntax parsing (visual query builder, syntax validation)\n- [Zustand](https://github.com/pmndrs/zustand) 5.0.9 for state management of external bundle configuration\n- [React Helmet (Async Fork)](https://github.com/staylor/react-helmet-async) 2.0.5 for webpage meta information\n\nFor development and building a few additional dependencies are required:\n\n- [Vite](https://vite.dev/) 7.3.1 with plugins\n  - [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)\n  - [picomatch](https://github.com/micromatch/picomatch#globbing-features) 4.0.3 for filename filters in output control\n- [TypeScript](https://www.typescriptlang.org/) 5.9.3 with `@types/*` definitions\n- [ESLint](https://eslint.org/) 9.39.2 with plugins\n- [simple-git](https://github.com/steveukx/git-js) 3.30.0 for source code information\n\n## Features\n\n- Modern, mobile-friendly, dark-mode, accessibility (ARIA) support\n- Single[¹](#footnote-1) \u003cabbr title=\"Single Page Application\"\u003eSPA\u003c/abbr\u003e bundle for easy integration\n- Various usability features like fuzzy filtering, tooltips, ...\n- Input support with query syntax highlighting and visual query builders (FCS-QL, LexCQL)\n\n\u003ca id=\"footnote-1\"\u003e¹\u003c/a\u003e 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.\n\n## Requirements\n\n- Node 22+ (due to `node:fs -\u003e globSync`)\n\n## How to deploy\n\n### Building\n\nRunning 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.\n\n```bash\nnpm run build\n```\n\nTo 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!\n\n```bash\nnpm run build:bundle\n```\n\nAn 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.\n\nEnvironment 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.\n\n- Disable language switcher (use only one locale): `VITE_LOCALES='[\"en\"]' npm run build`\n- Disable the visual query builder: `VITE_FEATURE_QUERY_BUILDER=false npm run build`\n\n### Configuration\n\nThe bundle can be pre-configured by adjusting the `import.meta.env.` constants found in the [`vite.config.ts`](vite.config.ts) configuration file.\n\n- \"branding\" related configs:\n  - `HEAD_TITLE`: the base application title for the browser\n  - `CANONCIAL_URL`: the canonical URL to the application (head meta information), _unused for now?_\n- deployment base configuration\n  - `DEPLOY_PATH`: the (sub-)path the application is served from, by default `/` for the root\n  - `API_URL`: the backend FCS SRU Aggregator REST API endpoint, **required!**\n  - `VALIDATOR_URL`: the URL to the FCS Endpoint Validator\n- optional features\n  - `SHOW_SEARCH_RESULT_LINK`: boolean, whether to display a semi-permanent search results link, _use only for development to avoid confusion_\n  - `FEATURE_TRACKING_MATOMO`: boolean, whether to include Matomo/Piwik tracking/statistics calls\n    - `FEATURE_TRACKING_MATOMO_PARAMS`: parameters for tracking setup, set with `JSON.stringify({})` where the parameter object `{}` should contain the following entries:\n      - `siteId`: number, required, for `setSiteId`\n      - `trackerUrl`: URL for tracking server, required, for `setTrackerUrl`, likely something like `\u003cbaseUrl\u003e/matomo.php`\n      - `enableLinkTracking`: boolean, optional, by default `true`, can be disabled\n      - `domains`: string[], optional, can be a list of to be considered \"local\" domain names, for `setDomains`\n      - `userId`: string, optional, will be hashed with [cyrb53](https://stackoverflow.com/a/52171480/9360161), for `setUserId`\n      - `srcUrl`: URL for JS script source to load Matomo/Piwik script, required, likely something like `\u003cbaseUrl\u003e/matomo.js`\n      - NOTE: if not set or any required value is likely invalid, then tracking will not be configured!\n  - `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.\n\nRuntime 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.\n\n- `DEPLOY_PATH`: the basename of the application, e.g. if deployed on some subpath like `example.org/aggregator/` use `/aggregator`, by default `/`\n- `API_URL`: the base URL to the FCS SRU Aggregator REST API, e.g. `https://contentsearch.clarin.eu/rest/`\n- `VALIDATOR_URL`: the base URL to the FCS Endpoint Validator, e.g. `https://www.clarin.eu/fcsvalidator/`\n- `SHOW_SEARCH_RESULT_LINK`: boolean (`true`/`false`) for whether to display a semi-permanent link to search results using the internal searchID\n- `APP_TITLE`: application title, by default `Content Search`\n- `APP_TITLE_HEAD`: application title, will be used for HTML HEAD title tag, by default `FCS Aggregator – Content Search`\n- `MATOMO_TRACKING_PARAMS`: matomo tracking parameters, see section about `FEATURE_TRACKING_MATOMO` above\n\n## Development\n\nBased 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.\n\nFor local testing run:\n\n```bash\nnpm run dev\n```\n\n### Update dependencies\n\n- Check possible upgrades with `npx npm-check-updates`\n- Check system information (for bug reports etc.) `npx envinfo --system --npmPackages --binaries --browsers`\n\n### Expanding the ESLint configuration (TODO)\n\nIf you are developing a production application, we recommend updating the configuration to enable type aware lint rules:\n\n- Configure the top-level `parserOptions` property like this:\n\n```js\nexport default tseslint.config({\n  languageOptions: {\n    // other options...\n    parserOptions: {\n      project: ['./tsconfig.node.json', './tsconfig.app.json'],\n      tsconfigRootDir: import.meta.dirname,\n    },\n  },\n})\n```\n\n- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`\n- Optionally add `...tseslint.configs.stylisticTypeChecked`\n- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:\n\n```js\n// eslint.config.js\nimport react from 'eslint-plugin-react'\n\nexport default tseslint.config({\n  // Set the react version\n  settings: { react: { version: '18.3' } },\n  plugins: {\n    // Add the react plugin\n    react,\n  },\n  rules: {\n    // other rules...\n    // Enable its recommended rules\n    ...react.configs.recommended.rules,\n    ...react.configs['jsx-runtime'].rules,\n  },\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarin-eric%2Ffcs-sru-aggregator-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclarin-eric%2Ffcs-sru-aggregator-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclarin-eric%2Ffcs-sru-aggregator-ui/lists"}