cludo-search-components

React components for building a Cludo search experience. The package is published as @cludosearch/cludo-search-components on the public npm registry and works with React 16.8.0 to 19.

Install

npm install @cludosearch/cludo-search-components

Usage

The package has three entry points. The root entry is for client side rendering, /ssr is for Next.js and other server rendering, and /styles is the stylesheet.

// Client side rendering
import { initCludo, CludoWrapper } from "@cludosearch/cludo-search-components";

// Server side rendering (Next.js and similar)
import { CludoWrapper } from "@cludosearch/cludo-search-components/ssr";

// Stylesheet
import "@cludosearch/cludo-search-components/styles";

Import the stylesheet yourself in most setups. The root entry only injects it when initCludo is called with cssTheme.

The root entry has an import condition only, so load it with ESM import. require() is not supported.

Documentation

• Component documentation and examples: Storybook. The Storybook currently documents the legacy @cludo package. The @cludosearch documentation is not published yet.
• Release notes: CHANGELOG.md. The changelog ships inside the package.

Upgrading from @cludo

The package was previously published as @cludo/cludo-search-components on GitHub Packages. That line stopped at 1.0.63 and is no longer updated. New releases are published only under the @cludosearch scope on npm, so rename your imports and install the new package. The first section of the changelog is the migration guide.

For Cludo developers

Contributing to the Library

For detailed contribution guidelines, please see our Confluence documentation.

Important Notes

• @cludosearch vs @cludo: For new features on the @cludosearch version (the version published on npm), base your branch off npm-migration-updates. The main branch is for the older @cludo version.
• Upgrading your project from @cludo to @cludosearch? See the migration guide for important information and best practices.

Local Development

Working with React Search Controller

Prerequisites

• A local project in the Cludo.CustomerTemplates repository
• Yalc installed globally: npm i yalc -g

Setup Steps

1. Clone and create a branch

   • Clone the cludo-search-components repository
   • Create a new feature branch following the naming convention: [f|h]/[JIRA-ID]-description
     • f/ for features, h/ for hotfixes
     • Example: f/REACT-32-new-categorized-serp-component

2. Prepare the library for local development

   cd cludo-search-components
   npm install
   npm i yalc -g
   yalc publish
   

3. Link to your local project

   cd /path/to/your/customer-template
   yalc link @cludosearch/cludo-search-components
   cludosearch dev
   

4. Develop and test

   • Make changes in the cludo-search-components directory
   • When ready to test changes:

     npm run build
     yalc publish --push
     

   • Your linked project will automatically recompile with the changes
   • Refresh your browser to see the updates

5. Cleanup when done

   yalc remove @cludosearch/cludo-search-components
   npm install @cludosearch/cludo-search-components
   

Working with React Search Core (Vite Projects)

1. Create a Vite project

   npm create vite@latest .
   

   Select React + TypeScript when prompted

2. Initialize React Search Core Follow the documentation to set up React Search Core

3. Link with Yalc Follow steps 2-4 from the React Search Controller section above

4. Configure Vite for local development Add to your vite.config.ts:

   optimizeDeps: {
     include: ["@cludosearch/cludo-search-components"],
   }
   

5. Clear Vite cache if needed If changes aren't appearing:

   rm -rf node_modules/.vite && rm -rf node_modules/.cache/vite
   

Publishing a New Version

Version Bumping

The library uses Semantic Versioning: MAJOR.MINOR.PATCH. The number tells consumers whether an update is safe to take.

When your version is already ahead of the base branch, the workflow skips its patch bump.

A change is breaking if it removes or renames an export, prop or type, makes a prop required, changes a default or a return value, changes markup or class names that templates style or query, or changes peerDependencies, exports or sideEffects. If unsure, treat it as breaking. Deprecate in a minor release before removing in a major one.

Full guide: Versioning the React component library.

Changelog

Every minor or major release adds a section to CHANGELOG.md (create the file if it does not exist yet), newest version first. Each breaking change gets three lines, followed by a before/after code example:

• What changed: the old and new behaviour, with the PR number and Jira key.
• Who is affected: a concrete setup readers can check against their own code.
• What to do: the action that fixes it.

For a major release, also add a Storybook migration page under src/stories/, because self-hosting customers read Storybook rather than the repo.

The search-components-changelog AI skill in the Cludo/ai repo classifies the change, sets the bump and drafts the entry. Ask Claude to "write the changelog entry for this PR".

Automatic Publishing to NPM

When a pull request is merged into the npm-migration-updates branch, the package is automatically published to the public npm registry using GitHub Actions.

Important: Every merge publishes the version in package.json, so check it matches the bump your change needs (see Version Bumping) before merging.

Beta Versions

To publish a beta version for testing (manual):

1. Append -beta.0 to the version (e.g., 1.0.75-beta.0)
2. Publish with: npm publish --tag beta
3. Install in consuming project: npm install @cludosearch/[email protected]

Running Storybook Locally

Versions 0.18.3+ include Storybook documentation:

npm install
npm run storybook