How to do that ?
#send a query from a nodejs backend without reactivity stuff
rain pine
jolly oxideBOT
Hi @rain pine. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
To send a query from a Node.js backend without reactivity, you should use the ConvexHttpClient instead of the ConvexClient. The HTTP client is designed for point-in-time queries without subscriptions.
Here's how to do it:
import { ConvexHttpClient } from "convex/browser";
import { api } from "./convex/_generated/api.js";
const client = new ConvexHttpClient(process.env["CONVEX_URL"]);
// either this
const count = await client.query(api.counter.get);
// or this
client.query(api.counter.get).then((count) => console.log(count));
The ConvexHttpClient works in Node.js and any JavaScript environment with fetch, and is specifically designed for server-side rendering, migrations, administrative scripts, and serverless functions to run queries at a single point in time - without the reactive subscriptions that come with the regular ConvexClient.
You can find a complete example in the Node.js Quickstart guide, which shows how to set up a Node.js project and query data from Convex using this approach.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
rain pine
@jolly oxide isn't there a way without creating a client I think ?
jolly oxideBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the knowledge sources provided, you need to create a client to query Convex from a Node.js backend. There isn't a documented way to query Convex without instantiating either a ConvexHttpClient or ConvexClient.
The knowledge sources consistently show that to interact with Convex from Node.js, you must:
- Create a client instance (either
ConvexHttpClientfor point-in-time queries orConvexClientfor subscriptions) - Use that client to call your queries
As shown in the Node.js documentation:
import { ConvexHttpClient } from "convex/browser";
import { api } from "./convex/_generated/api.js";
const httpClient = new ConvexHttpClient(CONVEX_URL_GOES_HERE);
httpClient.query(api.messages.list).then(console.log);
The only alternative mentioned in the knowledge sources is using HTTP Actions or the HTTP API, but these are for different use cases (receiving HTTP requests or making direct HTTP calls to Convex endpoints), and would still require making HTTP requests rather than avoiding client instantiation altogether.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
rain pine
@jolly oxide export const client = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL)
how to include auth with it ? I am using it from the browser
jolly oxideBOT
Let me check the knowledge base for you again. One moment! :books:
To include authentication with ConvexHttpClient in the browser, you need to use the setAuth() method to provide a JWT token. Here's how:
import { ConvexHttpClient } from "convex/browser";
const client = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
// Set authentication with a JWT token
const token = "your-jwt-token-here";
client.setAuth(token);
According to the ConvexHttpClient API documentation, the setAuth() method accepts a JWT-encoded OpenID Connect identity token as a string parameter. You should call this method whenever the token changes (e.g., due to expiration and refresh).
If you're using Clerk, you can get the token like this:
import { useAuth } from "@clerk/clerk-react";
const { getToken } = useAuth();
const token = await getToken({ template: "convex" });
if (token) {
client.setAuth(token);
}
Alternative: Pass auth during construction
You can also pass the auth token directly when creating the client:
const client = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL, {
auth: "your-jwt-token-here"
});
As noted in the ConvexHttpClient constructor documentation, this identity may expire, so for long-lived clients you may still need to call setAuth() later to refresh the token.
Important Note: For browser-based React applications, you typically wouldn't use ConvexHttpClient directly. Instead, you'd use ConvexReactClient with the appropriate auth provider wrapper (like ConvexProviderWithClerk or ConvexProviderWithAuth0), which handles authentication automatically. The ConvexHttpClient is more commonly used for server-side code or non-reactive scenarios.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
rain pine
@jolly oxide how to get token in browser ?
jolly oxideBOT
Let me check the knowledge base for you again. One moment! :books:
To get a JWT token in the browser for Convex authentication, the method depends on which authentication provider you're using:
With Clerk
import { useAuth } from "@clerk/clerk-react";
const { getToken } = useAuth();
const token = await getToken({ template: "convex" });
console.log(token);
With Auth0
import { useAuth0 } from "@auth0/auth0-react";
const { getAccessTokenSilently } = useAuth0();
const response = await getAccessTokenSilently({
detailedResponse: true,
});
const token = response.id_token;
console.log(token);
With Convex Auth
If you're using the Convex Auth library, you can use the useAuthToken() hook:
import { useAuthToken } from "@convex-dev/auth/react";
function SomeComponent() {
const token = useAuthToken();
// token will be a string or null
}
According to the Convex Auth API reference, this hook gives you access to the JWT token on the client for authenticating your Convex HTTP actions.