{"id":19403203,"url":"https://github.com/watson-developer-cloud/discovery-components","last_synced_at":"2026-03-11T17:03:06.989Z","repository":{"id":38550788,"uuid":"217359655","full_name":"watson-developer-cloud/discovery-components","owner":"watson-developer-cloud","description":"IBM Watson Discovery components","archived":false,"fork":false,"pushed_at":"2024-08-13T18:15:24.000Z","size":170236,"stargazers_count":21,"open_issues_count":26,"forks_count":38,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-22T02:23:20.893Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://watson-developer-cloud.github.io/discovery-components/storybook","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/watson-developer-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-10-24T17:49:03.000Z","updated_at":"2024-12-11T07:55:39.000Z","dependencies_parsed_at":"2023-02-19T12:00:25.301Z","dependency_job_id":"1be73e89-6258-47e3-acd7-e18592b47167","html_url":"https://github.com/watson-developer-cloud/discovery-components","commit_stats":{"total_commits":460,"total_committers":27,"mean_commits":"17.037037037037038","dds":0.6456521739130434,"last_synced_commit":"b03417bebaad4df6258a0d2033d58f1c4ea02e6e"},"previous_names":[],"tags_count":243,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watson-developer-cloud%2Fdiscovery-components","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watson-developer-cloud%2Fdiscovery-components/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watson-developer-cloud%2Fdiscovery-components/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/watson-developer-cloud%2Fdiscovery-components/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/watson-developer-cloud","download_url":"https://codeload.github.com/watson-developer-cloud/discovery-components/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253176444,"owners_count":21866141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-10T11:27:37.979Z","updated_at":"2026-03-11T17:03:06.909Z","avatar_url":"https://github.com/watson-developer-cloud.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discovery Components\n\n[![ci](https://github.com/watson-developer-cloud/discovery-components/workflows/ci/badge.svg)](https://github.com/watson-developer-cloud/discovery-components/actions?query=branch%3Amaster)\n[![Apache-2.0 license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/watson-developer-cloud/discovery-components/blob/master/LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/watson-developer-cloud/discovery-components/blob/master/.github/CONTRIBUTING.md)\n[![CLA assistant](https://cla-assistant.io/readme/badge/watson-developer-cloud/discovery-components)](https://cla-assistant.io/watson-developer-cloud/discovery-components)\n\n## Table of contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [About](#about)\n- [Quick Links](#quick-links)\n- [Using Discovery Components](#using-discovery-components)\n- [Prerequisites](#prerequisites)\n- [Development](#development)\n  - [Project structure](#project-structure)\n  - [Install](#install)\n  - [Commonly-used commands](#commonly-used-commands)\n    - [Root directory](#root-directory)\n    - [Example app (examples/discovery-search-app)](#example-app-examplesdiscovery-search-app)\n    - [React components (packages/discovery-react-components)](#react-components-packagesdiscovery-react-components)\n    - [Styles (packages/discovery-styles)](#styles-packagesdiscovery-styles)\n  - [Running the project](#running-the-project)\n  - [Running Storybook](#running-storybook)\n  - [Testing](#testing)\n    - [Unit/Integration testing](#unitintegration-testing)\n    - [Feature tests](#feature-tests)\n    - [Continuous integration](#continuous-integration)\n  - [Branching and Releasing](#branching-and-releasing)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## About\n\nThis is a repository created and maintained by the IBM Watson Discovery UI team. It contains a collection of components, to be used by internal and external applications to query [Watson Discovery](https://www.ibm.com/products/watson-discovery) projects. For a quick look at the available components, take a look at them in [Storybook](https://watson-developer-cloud.github.io/discovery-components/storybook/)\n\n## Quick Links\n\n- [Example App](./examples/discovery-search-app/README.md)\n- [React Components Library](./packages/discovery-react-components/README.md)\n- [Hosted Storybook](https://watson-developer-cloud.github.io/discovery-components/storybook/)\n\n## Using Discovery Components\n\nFirst, you will need to customize and improve your document retrieval project on the [Improve and Customize page](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-improvements) in IBM Watson Discovery. For example, you can [configure facets](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-facets), as well as the search bar and search results for your project. Then, you can build your application using Discovery Components, and it will pull in your specified project's configuration.\n\n## Prerequisites\n\n- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n- [nvm](https://github.com/nvm-sh/nvm#installation-and-update)\n  - Set Node version `nvm use` (uses value defined in `.nvmrc` file)\n- [yarn](https://yarnpkg.com/getting-started/install) or [npm](https://www.npmjs.com/get-npm)\n- On MacOS, install any waiting OS Software Updates and install Xcode Command Line Tools by running `xcode-select --install` in terminal.\n\n## Development\n\n### Project structure\n\nDiscovery Components is set up as a monorepo. At the top level, the `packages` directory contains all of the modules that are offered as part of this repository.\n\n[Lerna](https://github.com/lerna/lerna) and [Yarn](https://yarnpkg.com/) are used to manage shared dependencies across the packages.\nCreate React Library was used to generate the library of React components, `discovery-react-components`.\n\n### Install\n\n1. Install [Yarn](https://yarnpkg.com/getting-started/install), as it is required build the components locally.\n\n2. Download the git repository\n\n```\ngit clone git@github.com:watson-developer-cloud/discovery-components.git\n```\n\nor\n\n```\ngit clone https://github.com/watson-developer-cloud/discovery-components.git\n```\n\n3. Install OS dependencies for building NPM packages (required for building `cairo`, which is used by `pdfjs`):\n\n    Follow the installation instructions for your OS from https://github.com/Automattic/node-canvas#compiling.\n\n4. To generate the dependencies for all of the packages, run the following at the root directory:\n\n```\nyarn\n```\n\nThis will install and bundle all of the shared dependencies for `packages` and for `examples`, and will also create a single `yarn.lock` file at the root directory. Dependency hoisting is taken care of with [Yarn Workspaces](https://yarnpkg.com/features/workspaces), setup inside `package.json`.\n\n### Commonly-used commands\n\n#### Root directory\n\n| Command                                   | Description                                                                                   |\n| ----------------------------------------- | --------------------------------------------------------------------------------------------- |\n| `yarn`                                    | installs yarn dependencies in all of the packages                                             |\n| `yarn workspace \u003cpackage-name\u003e \u003ccommand\u003e` | runs the specified `yarn` script in the workspace of your choice (ex: `discovery-search-app`) |\n\n#### Example app (examples/discovery-search-app)\n\n[See here for a full list](./examples/discovery-search-app/README.md#available-commands)\n\n| Command             | Description                                                           |\n| ------------------- | --------------------------------------------------------------------- |\n| `yarn start`        | runs the client and runs the express server without configuring first |\n| `yarn start:client` | runs the client at http://localhost:3000/                             |\n| `yarn server:run`   | runs an express server without configuring first                      |\n\n#### React components (packages/discovery-react-components)\n\n[See here for a full list](./packages/discovery-react-components/README.md#available-commands)\n\n| Command                | Description                                                      |\n| ---------------------- | ---------------------------------------------------------------- |\n| `yarn build`           | uses `rollup` to create a production build of component library  |\n| `yarn test:watch`      | runs the unit/integration tests in watch mode                    |\n| `yarn storybook`       | runs storybook on http://localhost:9002                          |\n| `yarn storybook:build` | builds storybook artifacts locally (primarily for testing build) |\n\n#### Styles (packages/discovery-styles)\n\n| Command      | Description                                  |\n| ------------ | -------------------------------------------- |\n| `yarn start` | runs `sass` in `watch` mode                  |\n| `yarn build` | runs `sass` to compile `scss` files to `css` |\n\n### Running the project\n\nDeveloping `discovery-react-components` with real data and multiple components can be done using the [example app](./examples/discovery-search-app/README.md#running-the-example-app). To test the components in isolation with mock data, try [running Storybook](#running-storybook).\n\n### Running Storybook\n\nComponent documentation is done through Storybook.\n\nTo run Storybook, run the following command, then open your browser to `http://localhost:9002/`:\n\n```\nyarn workspace @ibm-watson/discovery-react-components run storybook\n```\n\n### Testing\n\n#### Unit/Integration testing\n\nThis repo uses [Jest](https://jestjs.io/) for unit and integration testing the React components. Tests are rendered through [react-testing-library](https://testing-library.com/), which also provides some additional functionality.\n\n#### Feature tests\n\n[Cypress](https://docs.cypress.io) is used for feature and e2e testing. All feature testing will be done in the `examples` directories (end-user application examples) to test a full client-server relationship. For CI, Cypress [server](https://docs.cypress.io/api/commands/server.html#Syntax) is used to mock out API requests and allow component expectations to be tested from the user's perspective.\n\nThe directory structure for adding feature tests in cypress looks like:\n\n```\nexamples/discovery-search-app/cypress\n├── fixtures         // mock data or other static assets\n│   └── example.json\n├── integration      // top-level directory for feature tests\n│   └── spec.ts\n├── plugins          // any plugins from https://docs.cypress.io/plugins/index.html#content\n│   └── index.js\n├── screenshots      // screenshots are stored on test failures\n├── support          // other helper methods like custom commands https://docs.cypress.io/api/cypress-api/custom-commands.html#Syntax\n│   ├── commands.ts\n│   └── index.ts\n└── videos           // recorded videos of test failures for review after a test run\n```\n\nThe basic process is to add a new file/directory under `examples/discovery-search-app/cypress/integration` then run `yarn workspace discovery-search-app cypress` to open up the interactive debugger.\n\nTo start the example app server and run all Cypress tests, use `yarn workspace discovery-search-app test:e2e`, which does the following steps:\n\n1. Starts up a server to host the example application\n2. Once the server responds, perform the next command `cypress run` (headless version of `cypress open`)\n3. After tests are complete, results are printed in the console, and both the cypress server and the application server are shut down\n\n#### Continuous integration\n\n[GitHub Actions](https://github.com/watson-developer-cloud/discovery-components/actions) is used to continuously run integration tests against this repository, and any PRs that are made against it.\n\nWhen triggered, GitHub Actions will build the project, then run the test scripts, and output the pass/fail to whichever branch/PR triggered the build.\n\nSteps in the automation can be set in `.github/workflows/ci.yml`, located in the root directory.\n\n### Branching and Releasing\n\n- `master` is an eternal branch with latest stable code that will have automated releases on using the continuous integration described above\n- for hotfix/patch-style releases, perform the following steps:\n  1. `git checkout -b hotfix/1.4.0-patch-1 v1.4.0-beta.2` (checks out a new branch from the tag needing the hotfix)\n  2. Make changes and push changes to `hotfix/1.4.0-patch-1` as usual\n  3. Ensure you have access to publish the package `npm login \u0026\u0026 npm whoami \u0026\u0026 npm access ls-collaborators` (must have `read-write`, contact someone from https://www.npmjs.com/settings/ibm-watson/members to gain access)\n  4. `lerna publish 1.4.0-patch-1.0 --dist-tag patch-1 --allow-branch hotfix/1.4.0` (see [lerna publish](https://github.com/lerna/lerna/tree/master/commands/publish))\n  5. `git checkout master \u0026\u0026 git merge hotfix/1.4.0 || git mergetool \u0026\u0026 git push origin master` (merge changes/tags back to `master`, resolving merge conflicts by taking `lerna.json` version from `master` branch)\n\nThe only branch permitted for automatic releasing on CI is `master`\n\nMore information about the `lerna publish` command can be found in the README for [lerna publish](https://github.com/lerna/lerna/tree/master/commands/publish)\n\nTo test publishing to the npm registry locally, you can use [Verdaccio](https://www.npmjs.com/package/verdaccio)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatson-developer-cloud%2Fdiscovery-components","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwatson-developer-cloud%2Fdiscovery-components","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwatson-developer-cloud%2Fdiscovery-components/lists"}