Codestin Search App

The @context-dot-dev/convex component calls Context.dev from your Convex backend with typed inputs and responses. This guide starts with a page scrape; the same client supports company lookups and other API operations.

View Context.dev for Convex

Open the component listing, package links, and current method catalog.

Prerequisites

An existing Convex project
A Context.dev account and a secret key from the dashboard

Install and configure

Install the package

npm install @context-dot-dev/convex

Add the component and its environment contract to convex/convex.config.ts:

import contextDev from "@context-dot-dev/convex/convex.config.js";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({
  env: {
    CONTEXT_DEV_API_KEY: v.string(),
  },
});

app.use(contextDev, {
  env: {
    CONTEXT_DEV_API_KEY: app.env.CONTEXT_DEV_API_KEY,
  },
});

export default app;

Set the deployment secret

Set the key interactively so it does not appear in shell history, then start Convex development:

npx convex env set CONTEXT_DEV_API_KEY
npx convex dev

Convex environment variables are deployment-specific. Set the same variable separately for production, using the --prod option, before deploying.

Keep CONTEXT_DEV_API_KEY in the Convex deployment environment. Do not put it in .env files committed to source control or pass it from browser code.

Call Context.dev from an action

Create a shared typed client and call it inside a Convex action. For example, add convex/context.ts:

import { ContextDev } from "@context-dot-dev/convex";
import { v } from "convex/values";

import { components } from "./_generated/api.js";
import { action } from "./_generated/server.js";

const contextDev = new ContextDev(components.contextDev);

export const scrapeMarkdown = action({
  args: { url: v.string() },
  handler: async (ctx, { url }) => {
    return await contextDev.scrapeMarkdown(ctx, {
      params: { url },
    });
  },
});

Run the action against the development deployment:

npx convex run context:scrapeMarkdown '{"url":"https://www.context.dev"}'

Inspect the returned markdown field to confirm the action reached Context.dev.

Context.dev methods must run in Convex actions because they make external HTTP requests. Do not call the component directly from a query or mutation.

Common methods

Method	Result
`scrapeMarkdown` / `scrapeHtml`	Clean Markdown or rendered HTML for a known URL
`search` / `crawl`	Current search results or pages from a focused site crawl
`extract`	Data matching a JSON Schema you provide
`retrieveBrand`	Logos, colors, company information, links, and industry data
`styleguide` / `fonts`	Detected design tokens and font usage
`screenshot`	A rendered webpage screenshot

GET-backed helpers take params. POST-backed helpers take body and may also take params when the operation defines query parameters. TypeScript infers both the arguments and responses from the component.

Data and caching

The component returns API results to your action but does not persist them in Convex. Store a result in your own tables only when your application needs it. Context.dev controls upstream caching through request parameters such as maxAgeMs.

Troubleshooting

Symptom	Fix
`components.contextDev` is missing	Run `npx convex dev` so Convex registers the component and regenerates `_generated`.
The action reports a missing environment variable	Set `CONTEXT_DEV_API_KEY` on the deployment you are calling, not only another development or production deployment.
A query or mutation cannot call the component	Move the external request into an `action`; queries and mutations cannot make arbitrary HTTP requests.
The API returns an authentication error	Replace the deployment secret with a current `ctxt_secret_` key from the Context.dev dashboard.

Reference

Component source

README, helper methods, generated bindings, examples, and tests.

npm package

Published package versions and install metadata.

Convex components

How components are installed, configured, and called.

Context.dev API quickstart

Authentication, endpoint behavior, and API examples.

AI chat

Frameworks

No-code tools

Convex

View Context.dev for Convex

Prerequisites

Install and configure

Call Context.dev from an action

Common methods

Data and caching

Troubleshooting

Reference

Component source

npm package

Convex components

Context.dev API quickstart

View Context.dev for Convex

​Prerequisites

​Install and configure

​Call Context.dev from an action

​Common methods

​Data and caching

​Troubleshooting

​Reference

Component source

npm package

Convex components

Context.dev API quickstart

Prerequisites

Install and configure

Call Context.dev from an action

Common methods

Data and caching

Troubleshooting

Reference