Node.js Quickstart
Learn how to query data from Convex in a Node.js project.
- Create a new npm project
Create a new directory for your Node.js project.
mkdir my-project && cd my-project
- Install the Convex client and server library
Install the
convex
package which provides a convenient interface for working with Convex from JavaScript.Also install the
dotenv
library for loading.env
files.npm install convex dotenv
- Setup a Convex dev deployment
Next, run
npx convex dev
. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.It will also create a
convex/
folder for you to write your backend API functions in. Thedev
command will then continue running to sync your functions with your dev deployment in the cloud.npx convex dev
- Create sample data for your database
In a new terminal window, create a
sampleData.jsonl
file with some sample data.sampleData.jsonl{"text": "Buy groceries", "isCompleted": true}
{"text": "Go for a swim", "isCompleted": true}
{"text": "Integrate Convex", "isCompleted": false} - Add the sample data to your database
Now that your project is ready, add a
tasks
table with the sample data into your Convex database with theimport
command.npx convex import tasks sampleData.jsonl
- Expose a database query
Add a new file
getTasks.js
in theconvex/
folder with a query function that loads the data.The default export declares an API function named after the file,
"getTasks"
.convex/getTasks.jsimport { query } from "./_generated/server";
export default query(async ({ db }) => {
return await db.query("tasks").collect();
}); - Connect the script to your backend
In a new file
script.js
, create aConvexHttpClient
using the URL of your development environment.script.jsconst { ConvexHttpClient } = require("convex/browser");
require("dotenv").config({ path: ".env.local" });
const client = new ConvexHttpClient(process.env["CONVEX_URL"]);
client.query("getTasks").then(console.log); - Run the script
Run the script from the same directory and see the list of tasks logged to the terminal.
node script.js