---
name: bijection-convex-smart-tags
description: "Evaluate and integrate the smart-tags component with Bijection."
---

# smart-tags

A Convex component for smart tagging and categorization with hierarchy and analytics

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-smart-tags
- Source: https://github.com/itsminhz/convex-smart-tags
- npm: https://www.npmjs.com/package/convex-smart-tags
- Directory: https://bijection.com/components/convex-smart-tags

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-smart-tags. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses smart-tags. Follow the installation and configuration steps exactly.

# smart-tags

## Instructions

convex-smart-tags is a Convex component that adds tagging infrastructure across any table in your Convex project. It provides tag CRUD, parent-child tag hierarchies with ancestor traversal, daily usage tracking, and trending calculations through a type-safe TypeScript client wrapper. The component registers its own tables (tags, entityTags, tagHierarchy, tagAnalytics) and exposes a clean API callable from mutations and queries without any schema modifications to your existing tables.

### Installation

```bash
npm install convex-smart-tags
```

Current npm version: `convex-smart-tags@0.1.1`

## Use cases

- Adding user-defined labels to heterogeneous entity types (posts, comments, products) from a single shared tag store without duplicating tagging logic per table
- Building a content taxonomy where tags have parent-child relationships and you need ancestor chain lookups or subtree queries (e.g., 'technology' -> 'ai' -> 'llms')
- Surfacing trending or popular tags over a configurable time window for a discovery or search feature
- Auditing cross-table tag usage to understand which entity types use which tags and at what volume
- Bootstrapping a tagging system quickly in a Convex project without writing custom schema, indexes, and query logic from scratch

## How it works

Register the component in `convex/convex.config.ts` using `app.use(smartTags)`. This mounts the component's internal tables (tags, entityTags, tagHierarchy, tagAnalytics) into your Convex deployment under its own namespace, leaving your existing schema untouched.

Instantiate the `SmartTags` client with `new SmartTags(components.smartTags)` inside your server-side files. The client exposes methods like `addTag`, `removeTag`, `getTagsForEntity`, and `getEntitiesByTag`, each taking a `tableName` and `entityId` string so tags are scoped per entity type without requiring foreign key constraints or schema changes.

Hierarchy is managed via `createTagHierarchy`, `getChildTags`, and `getTagAncestors`. These operate on the tagHierarchy table, which is indexed by parent and child tag name, enabling traversal in both directions.

Analytics are tracked automatically at the daily granularity in the tagAnalytics table. `getTrendingTags` accepts a `timeRange` in milliseconds and returns tags ranked by usage velocity, while `getTagStats` returns per-tag aggregate counts including recent trend data.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by smart-tags is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-smart-tags)
- [GitHub repository](https://github.com/itsminhz/convex-smart-tags)
- [Live demo](https://github.com/itsminhz/convex-smart-tags)
- [Convex Components Directory](https://www.convex.dev/components/convex-smart-tags)
- [Convex documentation](https://docs.convex.dev)