Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omavashia2005/ai-tool-elements/llms.txt

Use this file to discover all available pages before exploring further.

ai-tool-elements welcomes contributions — new connectors, bug fixes, component improvements, and test coverage. This guide covers the development workflow from initial setup through opening a pull request, following the conventions documented in CONTRIBUTING.md and SETUP.md.

​
Development setup

1

Clone and install

Clone the repository and install dependencies with npm ci to use the exact versions recorded in the lockfile.
git clone https://github.com/omavashia2005/ai-tool-elements.git
cd ai-tool-elements
npm ci
2

Run tests

Verify the environment is working before making any changes.
npm test
npm test builds the package, generates type declarations and CSS, then runs the Node test suite. A clean pass confirms that the build toolchain and your Node version (18 or later) are compatible.
3

Start the showcase

For visual and component changes, run the editable Next.js showcase alongside your editor.
npm run example
Then edit examples/basic/app/page.tsx to see live changes reflected in the browser. The showcase is a full Next.js app wired to the local build output, so changes to src/ take effect after the next npm run build (or re-running npm run example).

​
Project conventions

Follow these conventions when preparing a contribution. They keep the library small, stable, and easy to consume across different stacks.
  • Keep the public API vendor-neutral. Do not introduce abstractions that tie the library to a specific AI provider, framework, or backend.
  • Reuse the existing Tool, ToolField, and ToolImage types. Adding new top-level types requires a strong justification.
  • Keep connector IDs stable and unique. IDs are kebab-case slugs (e.g. "google-sheets"). Once published, an ID must not change — consumers depend on it to identify connectors.
  • Prefer per-icon @thesvg/icons/<slug> imports over barrel imports. Import the exact subpath (@thesvg/icons/slack) rather than the package root to avoid pulling in all icons at build time.
  • Add dependencies only when the existing stack cannot do the job. The goal is a lean dependency tree; evaluate whether clsx, tailwind-merge, or standard browser APIs can cover the use case first.
  • Include a small regression test for behavior changes. The test/ directory contains Node test suite files. New behavior should be covered so future changes do not silently regress it.

​
Useful commands

npm run build          # Build library (ESM, CJS, types, CSS)
npm run example        # Run Next.js showcase with live reload
npm run example:build  # Static build of the showcase
npm run doctor         # Run react-doctor checks
npm run build produces dist/index.js (ESM), dist/index.cjs (CJS), dist/index.d.ts (type declarations), and dist/index.css (minified Tailwind CSS). Always run npm test rather than npm run build alone before opening a PR, because npm test also executes the test suite.

​
Pull requests

  • Open development pull requests against the dev branch, not main.
  • Explain what changed and why in the PR description — a one-liner is fine for small fixes, but connector additions and API changes warrant more detail.
  • Keep unrelated formatting changes, generated catalog updates, and dependency bumps out of the pull request. These are easier to review and revert when isolated.
  • main requires the Test status check to pass before a PR can be merged. Make sure npm test passes locally on a clean install before pushing.

​
Release workflow

Releases are managed by the maintainers and follow a structured branch-and-tag process.
  1. Create a release branch from dev: 
    VERSION=0.1.2
git switch dev && git pull --ff-only
git switch -c "release/v$VERSION"
  2. Bump the version and run tests: 
    npm version "$VERSION" --no-git-tag-version
npm test
git add package.json package-lock.json
git commit -m "release: v$VERSION"
git push -u origin "release/v$VERSION"
  3. Open a pull request from release/vX.Y.Z to main. After Test passes, merge without squashing.
  4. Create a GitHub Release targeting main with tag vX.Y.Z and publish it. The publish.yml GitHub Actions workflow verifies the tag and publishes the package to npm automatically — no npm token is required in the workflow.
  5. Fast-forward dev to the released commit so the default branch stays in sync with main.
All contributions are licensed under the MIT License.

Build docs developers (and LLMs) love

Get started for freeTalk to us