Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 228 lines 9.02 KB
Rendered Raw
1 # Toolkits Page - Implementation Plan
2
3 ## Decisions Made
4
5 ### No Sidebar
6 - Toolkits section has no sidebar navigation
7 - Only breadcrumb navigation (`← Back to Toolkits`)
8 - Keeps UI clean, avoids 855 items in sidebar
9
10 ### No Input Parameters on Toolkit Pages
11 - Users don't need param schemas in docs
12 - LLMs read schemas automatically
13 - Platform playground is better for exploring params
14
15 ### No Scopes Display
16 - We only have scope names, not descriptions
17 - Raw scope strings aren't useful to users
18 - Just show auth method badge (OAuth2, API_KEY, etc.)
19
20 ### Search-First Experience
21 - Landing page shows search + category filter + cards
22 - Don't render all 855 cards upfront
23 - Filter client-side from pre-generated JSON
24 - The Instant Tools card toggles an eligibility filter and intersects with search.
25 The guide remains a separate link. Instant eligibility is refreshed through the
26 server-only `/api/toolkits/instant` route from the paginated production catalog,
27 cached for five minutes and merged only into existing snapshot rows. Missing
28 eligibility or failed requests show a retry state, not a false empty catalog.
29 The API key stays on the server. Neutral Nucleo outline bolts match the
30 dashboard; a filled bolt denotes the selected filter, not project access.
31
32 ### Build-Time Generation
33 - `bun run generate:toolkits` - separate command
34 - Not run on `bun run dev` (too slow)
35 - Run on CI push
36 - JSON files committed to git (works offline)
37
38 ---
39
40 ## URL Structure
41
42 ```
43 /toolkits → Landing page (search + filter + cards)
44 /toolkits/pro-tools → Pro tools pricing/limits info
45 /toolkits/{slug} → Individual toolkit page
46 ```
47
48 ---
49
50 ## Landing Page (`/toolkits`)
51
52 ```
53 ┌─────────────────────────────────────────────────────────────┐
54 │ Toolkits [Request Tools →] │
55 │ All the toolkits that we support. │
56 │ │
57 │ 🔍 Search toolkits... │
58 │ │
59 │ [All] [Communication] [Developer Tools] [CRM] [Storage]... │
60 │ │
61 │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
62 │ │ Gmail │ │ Slack │ │ GitHub │ │
63 │ │ GMAIL │ │ SLACK │ │ GITHUB │ │
64 │ │ desc... │ │ desc... │ │ desc... │ │
65 │ │[OAUTH2] │ │[OAUTH2] │ │[OAUTH2] │ │
66 │ │ 🔧37 ⚡2 │ │ 🔧130 ⚡9│ │ 🔧829 ⚡6│ │
67 │ └─────────┘ └─────────┘ └─────────┘ │
68 │ │
69 │ ⭐ Some tools are pro tools. [Learn about pricing →] │
70 └─────────────────────────────────────────────────────────────┘
71 ```
72
73 ---
74
75 ## Individual Toolkit Page (`/toolkits/{slug}`)
76
77 ```
78 ┌─────────────────────────────────────────────────────────────┐
79 │ ← Back to Toolkits │
80 │ │
81 │ [Logo] Gmail [Open in Platform →] │
82 │ GMAIL (copy) │
83 │ Gmail is Google's email service... │
84 │ │
85 │ [OAuth2] 37 Tools 2 Triggers Communication │
86 ├─────────────────────────────────────────────────────────────┤
87 │ ## Authentication │
88 │ This toolkit uses OAuth2. │
89 │ [Create Auth Config →] [How authentication works →] │
90 ├─────────────────────────────────────────────────────────────┤
91 │ ## Tools │
92 │ 🔍 Search tools... │
93 │ │
94 │ | Name | Description │
95 │ |-------------------|---------------------------------------|
96 │ | Send email | Sends an email message to... │
97 │ | Create draft | Creates a draft email... │
98 ├─────────────────────────────────────────────────────────────┤
99 │ ## Triggers (only if count > 0) │
100 │ | Name | Description │
101 │ |-------------------|---------------------------------------|
102 │ | New email | Fires when a new email arrives... │
103 └─────────────────────────────────────────────────────────────┘
104 ```
105
106 ---
107
108 ## Data & Generation
109
110 ### Single File Architecture
111
112 All toolkit data (including tools and triggers) is stored in a **single JSON file**:
113
114 ```
115 /public/data/toolkits.json → All toolkits with tools & triggers (~5-10MB)
116 ```
117
118 ### Why Single File?
119
120 - **Fully static** - No API calls at runtime, fast and reliable
121 - **No repo bloat** - One file instead of 800+ individual files
122 - **Git-friendly** - Git compresses JSON well
123 - **Simple** - Easy to understand and maintain
124 - **Open source friendly** - Public data, no secrets
125
126 ### Generator Script
127 `scripts/generate-toolkits.ts`
128
129 Run: `bun run generate:toolkits`
130
131 ### JSON Structure
132
133 ```json
134 // toolkits.json
135 [
136 {
137 "slug": "gmail",
138 "name": "Gmail",
139 "logo": "https://...",
140 "description": "Gmail is Google's...",
141 "category": "Communication",
142 "authSchemes": ["OAUTH2"],
143 "toolCount": 37,
144 "triggerCount": 2,
145 "version": "20260102_00",
146 "tools": [
147 { "slug": "GMAIL_SEND_EMAIL", "name": "Send email", "description": "..." }
148 ],
149 "triggers": [
150 { "slug": "GMAIL_NEW_EMAIL", "name": "New email", "description": "..." }
151 ]
152 }
153 ]
154 ```
155
156 ---
157
158 ## Scripts
159
160 ```json
161 {
162 "scripts": {
163 "dev": "next dev",
164 "build": "next build",
165 "generate:toolkits": "bun scripts/generate-toolkits.ts"
166 }
167 }
168 ```
169
170 | Command | Regenerates? | Use case |
171 |---------|--------------|----------|
172 | `bun run dev` | ❌ | Local dev |
173 | `bun run build` | ❌ | Fast build |
174 | `bun run generate:toolkits` | ✅ | Manual |
175 | CI push | ✅ | Auto regenerate |
176
177 ---
178
179 ## Components to Build
180
181 1. `ToolkitSearch` - Search input
182 2. `CategoryFilter` - Filter chips
183 3. `ToolkitCard` - Individual card
184 4. `ToolkitGrid` - Cards container
185 5. `ToolsTable` - Searchable tools table
186 6. `Breadcrumb` - Navigation
187
188 ---
189
190 ## Implementation Order
191
192 1. [x] Generator script (`scripts/generate-toolkits.ts`)
193 2. [x] Landing page + components (category grouping, alphabet sections)
194 3. [x] Individual toolkit page (version display, auth badges, tool/trigger list with copy)
195 4. [x] Pro tools page (`/toolkits/pro-tools`)
196 5. [x] Hybrid architecture (static index + server-side API fetch)
197 6. [ ] Polish/styling
198 7. [ ] CI hooks for auto-regeneration
199
200 ---
201
202 ## FAQ Section
203
204 ### How It Works
205 - Per-toolkit FAQ sourced from plain markdown files in `content/toolkits/faq/{toolkit-slug}.md`
206 - `##` headings are questions, body text is the answer
207 - Markdown is converted to HTML at build time using `remark-parse` + `remark-rehype` + `hast-util-to-html` (all transitive deps from Fumadocs, no new packages)
208 - Rendered as Fumadocs `Accordion` components between the Header and Auth Details sections
209 - Only shown if a `.md` file exists for that toolkit and has valid Q&A content
210
211 ### Copy Page / LLM Markdown
212 - FAQ content is also included in the `/toolkits/{slug}.md` LLM route output
213 - Heading levels are bumped (`##` → `###`) so questions are children of the `## Frequently Asked Questions` section
214
215 ### No Sitemap Impact
216 - FAQ is embedded within existing toolkit pages — no new URLs are created
217 - No changes to sitemap or routing
218
219 ### Adding FAQ Content
220 - Create/edit `content/toolkits/faq/{toolkit-slug}.md` — no code changes needed
221 - Empty files or files with no valid `##` headings are safely ignored
222
223 ---
224
225 ## Future: CI Hooks
226
227 - Trigger docs regeneration from toolkit repo changes
228 - Trigger docs regeneration from API repo changes